Update documentation

docs/docs/basic-usage.md

@@ -65,7 +65,7 @@ It will automatically find a suitable version constraint.
 ### Version constraints
 ### Version constraints
 
 
 In our example, we are requesting the `pendulum` package with the version constraint `^1.4`.
 In our example, we are requesting the `pendulum` package with the version constraint `^1.4`.
-This means any version geater or equal to 1.4.0 and less than 2.0.0 (`>=1.4.0 <2.0.0`).
+This means any version greater or equal to 1.4.0 and less than 2.0.0 (`>=1.4.0 <2.0.0`).
 
 
 Please read [versions](/versions/) for more in-depth information on versions, how versions relate to each other, and on version constraints.
 Please read [versions](/versions/) for more in-depth information on versions, how versions relate to each other, and on version constraints.
 
 
@@ -77,7 +77,7 @@ Please read [versions](/versions/) for more in-depth information on versions, ho
     When you specify a dependency in `pyproject.toml`, Poetry first take the name of the package
     When you specify a dependency in `pyproject.toml`, Poetry first take the name of the package
     that you have requested and searches for it in any repository you have registered using the `repositories` key.
     that you have requested and searches for it in any repository you have registered using the `repositories` key.
     If you have not registered any extra repositories, or it does not find a package with that name in the
     If you have not registered any extra repositories, or it does not find a package with that name in the
-    repositories you have specified, it falls bask on PyPI.
+    repositories you have specified, it falls back on PyPI.
     
     
     When Poetry finds the right package, it then attempts to find the best match
     When Poetry finds the right package, it then attempts to find the best match
     for the version constraint you have specified.
     for the version constraint you have specified.
@@ -143,7 +143,7 @@ and update the lock file with the new versions.
 
 
 !!!note
 !!!note
 
 
-    Poetry will display a Warning when executing an install command if `pyproject.lock` and `pyproject.toml`
+    Poetry will display a **Warning** when executing an install command if `pyproject.lock` and `pyproject.toml`
     are not synchronized.
     are not synchronized.
 
 
 
 
@@ -159,5 +159,5 @@ or create a brand new one for you to always work isolated from your global Pytho
     `poetry` has been installed.
     `poetry` has been installed.
     
     
     What this means is if you project is Python 2.7 only you should
     What this means is if you project is Python 2.7 only you should
-    install `poetry` for you global Python 2.7 executable and use
+    install `poetry` for your global Python 2.7 executable and use
     it to manage your project.
     it to manage your project.

docs/docs/cli.md

@@ -226,7 +226,7 @@ Note that, at the moment, only pure python wheels are supported.
 
 
 ## publish
 ## publish
 
 
-This command builds (if not already built) and publishes the package to the remote repository.
+This command publishes the package, previously built with the [`build`](#build) command, to the remote repository.
 
 
 It will automatically register the package before uploading if this is the first time it is submitted.
 It will automatically register the package before uploading if this is the first time it is submitted.
 
 
@@ -234,6 +234,8 @@ It will automatically register the package before uploading if this is the first
 poetry publish
 poetry publish
 ```
 ```
 
 
+It can also build the package if you pass it the `--build` option.
+
 ### Options
 ### Options
 
 
 * `--repository (-r)`: The repository to register the package to (default: `pypi`).
 * `--repository (-r)`: The repository to register the package to (default: `pypi`).

docs/docs/faq.md

-# Third Party Libraries
+# FAQ
 
 
-Poetry 
+## Why is the dependency resolution process slow?
+
+While the dependency resolver at the heart of Poetry is highly optimized and
+should be fast enough for most cases, sometimes, with some specific set of dependencies,
+it can take time to find a valid solution.
+
+This is due to the fact that not all libraries on PyPI have properly declared their metadata
+and, as such, they are not available via the PyPI JSON API. At this point, Poetry has no choice
+but downloading the packages and inspect them to get the necessary information. This is an expensive
+operation, both in bandwidth and time, which is why it seems this is a long process.
+
+At the moment there is not way around it.
+
+!!!note
+
+    Once Poetry has cached the releases' information, the dependency resolution process
+    will be much faster.
+
+## Why are unbound version constraints a bad idea?
+
+A version constraint without an upper bound such as `*` or `>=3.4` will allow updates to any future version of the dependency.
+This includes major versions breaking backward compatibility.
+
+Once a release of your package is published, you cannot tweak its dependencies anymore in case a dependency breaks BC
+- you have to do a new release but the previous one stays broken.
+
+The only good alternative is to define an upper bound on your constraints,
+which you can increase in a new release after testing that your package is compatible
+with the new major version of your dependency.
+
+For example instead of using `>=3.4` you should use `~3.4` which allows all versions `<4.0`.
+The `^` operator works very well with libraries following [semantic versioning](https://semver.org).

docs/docs/index.md

@@ -60,9 +60,40 @@ If you want to install prerelease versions, you can use the `--preview` option.
 poetry self:update --preview
 poetry self:update --preview
 ```
 ```
 
 
-And finally, if you want to install a spcific version you can pass it as an argument
+And finally, if you want to install a specific version you can pass it as an argument
 to `self:update`.
 to `self:update`.
 
 
 ```bash
 ```bash
 poetry self:update 0.8.0
 poetry self:update 0.8.0
 ```
 ```
+
+
+## Enable tab completion for Bash, Fish, or Zsh
+
+`poetry` supports generating completion scripts for Bash, Fish, and Zsh.
+See `poetry help completions` for full details, but the gist is as simple as using one of the following:
+
+
+```bash
+# Bash
+poetry completions bash > /etc/bash_completion.d/poetry.bash-completion
+
+# Bash (macOS/Homebrew)
+poetry completions bash > $(brew --prefix)/etc/bash_completion.d/poetry.bash-completion
+
+# Fish
+poetry completions fish > ~/.config/fish/completions/poetry.fish
+
+# Zsh
+poetry completions zsh > ~/.zfunc/_poetry
+```
+
+!!! note
+
+    You may need to restart your shell in order for the changes to take effect.
+    
+For `zsh`, you must then add the following line in your `~/.zshrc` before `compinit`:
+
+```bash
+fpath+=~/.zfunc
+```

docs/docs/versions.md

@@ -108,6 +108,13 @@ my-package = { path = "../my-package/" }
 my-package = { path = "../my-package/dist/my-package-0.1.0.tar.gz" }
 my-package = { path = "../my-package/dist/my-package-0.1.0.tar.gz" }
 ```
 ```
 
 
+!!!note
+
+    You can install path dependencies in editable/development mode.
+    Just pass `--develop my-package` (repeatable as much as you want) to
+    the `install` command.
+    
+
 ### Python restricted dependencies
 ### Python restricted dependencies
 
 
 You can also specify that a dependency should be installed only for specific Python versions:
 You can also specify that a dependency should be installed only for specific Python versions:

docs/mkdocs.yml

@@ -15,6 +15,7 @@ pages:
   - Repositories: repositories.md
   - Repositories: repositories.md
   - Versions: versions.md
   - Versions: versions.md
   - The pyproject.toml file: pyproject.md
   - The pyproject.toml file: pyproject.md
+  - FAQ: faq.md
 
 
 markdown_extensions:
 markdown_extensions:
   - codehilite
   - codehilite