Update docs

docs/docs/basic-usage.md

@@ -45,7 +45,7 @@ If you want to add dependencies to your project, you can specify them in the `to
 
 
 ```toml
 ```toml
 [tool.poetry.dependencies]
 [tool.poetry.dependencies]
-requests = "^2.18"
+pendulum = "^1.4"
 ```
 ```
 
 
 As you can see, it takes a mapping of **package names** and **version constraints**.
 As you can see, it takes a mapping of **package names** and **version constraints**.
@@ -60,3 +60,87 @@ $ poetry add pendulum
 ```
 ```
 
 
 It will automatically find a suitable version constraint.
 It will automatically find a suitable version constraint.
+
+### Version constraints
+
+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`).
+
+Please read [versions](/versions/) for more in-depth information on versions, how versions relate to each other, and on version constraints.
+
+
+!!!note
+
+    **How does Poetry download the right files?**
+    
+    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.
+    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.
+    
+    When Poetry finds the right package, it then attempts to find the best match
+    for the version constraint you have specified.
+    
+
+## Installing dependencies
+
+To install the defined dependencies for your project, just run the `install` command.
+    
+```bash
+poetry install
+```
+
+When you run this command, one of two things may happen:
+
+### Installing without `pyproject.lock`
+
+If you have never run the command before and there is also no `pyproject.lock` file present,
+Poetry simply resolves all dependencies listed in your `pyproject.toml` file and downloads the latest version of their files.
+
+When Poetry has finished installing, it writes all of the packages and the exact versions of them that it downloaded to the `pyproject.lock` file,
+locking the project to those specific versions.
+You should commit the `pyproject.lock` file to your project repo so that all people working on the project are locked to the same versions of dependencies (more below).
+
+
+### Installing with `pyproject.lock`
+
+This brings us to the second scenario. If there is already a `pyproject.lock` file as well as a `pyproject.toml` file
+when you run `poetry install`, it means either you ran the `install` command before,
+or someone else on the project ran the `install` command and committed the `pyproject.lock` file to the project (which is good).
+
+Either way, running `install` when a `pyproject.lock` file is present resolves and installs all dependencies that you listed in `pyproject.toml`,
+but Poetry uses the exact versions listed in `pyproject.lock` to ensure that the package versions are consistent for everyone working on your project.
+As a result you will have all dependencies requested by your `pyproject.toml` file,
+but they may not all be at the very latest available versions
+(some of the dependencies listed in the `pyproject.lock` file may have released newer versions since the file was created).
+This is by design, it ensures that your project does not break because of unexpected changes in dependencies.
+
+### Commit your `pyproject.lock` file to version control
+
+Committing this file to VC is important because it will cause anyone who sets up the project
+to use the exact same versions of the dependencies that you are using.
+Your CI server, production machines, other developers in your team,
+everything and everyone runs on the same dependencies,
+which mitigates the potential for bugs affecting only some parts of the deployments.
+Even if you develop alone, in six months when reinstalling the project you can feel confident
+the dependencies installed are still working even if your dependencies released many new versions since then.
+(See note below about using the update command.)
+
+!!!note
+
+    For libraries it is not necessary to commit the lock file.
+    
+
+## Updating dependencies to their latest versions
+
+As mentioned above, the `pyproject.lock` file prevents you from automatically getting the latest versions
+of your dependencies.
+To update to the latest versions, use the `update` command.
+This will fetch the latest matching versions (according to your `pyproject.toml` file)
+and update the lock file with the new versions.
+(This is equivalent to deleting the `pyproject.lock` file and running `install` again.)
+
+!!!note
+
+    Poetry will display a Warning when executing an install command if `pyproject.lock` and `pyproject.toml`
+    are not synchronized.

docs/docs/cli.md

+# Commands
+
+You've already learned how to use the command-line interface to do some things.
+This chapter documents all the available commands.
+
+To get help from the command-line, simply call `poetry` or `poetry list` to see the complete list of commands,
+then `--help` combined with any of those can give you more information.
+
+As `Poetry` uses [cleo](https://github.com/sdispater/cleo) you can call commands by short name if it's not ambiguous.
+
+```bash
+poetry up
+```
+
+calls `poetry update`.
+
+
+## Global options
+
+* `--verbose (-v|vv|vvv)`: Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug.
+* `--help (-h)` : Display help information.
+* `--quiet (-q)` : Do not output any message.
+* `--ansi`: Force ANSI output.
+* `--no-ansi`: Disable ANSI output.
+* `--version (-V)`: Display this application version.
+
+
+## new
+
+This command will help you kickstart your new Python project by creating
+a directory structure suitable for most projects.
+
+```bash
+poetry new my-package
+```
+
+will create a folder as follows:
+
+```text
+my-package
+├── pyproject.toml
+├── README.rst
+├── my_package
+│   └── __init__.py
+└── tests
+    ├── __init__.py
+    └── test_my_package
+```
+
+If you want to name your project differently than the folder, you can pass
+the `--name` option:
+
+```bash
+poetry new my-folder --name my-package
+```
+
+## install
+
+The `install` command reads the `pyproject.toml` file from the current directory, resolves the dependencies,
+and installs them.
+
+```bash
+poetry install
+```
+
+If there is a `pyproject.lock` file in the current directory,
+it will use the exact versions from there instead of resolving them.
+This ensures that everyone using the library will get the same versions of the dependencies.
+
+If there is no `pyproject.lock` file, Poetry will create one after dependency resolution.
+
+You can specify to the command that you do not want the development dependencies installed by passing
+the `--no-dev` option.
+
+```bash
+poetry install --no-dev
+```
+
+You can also specify the extras you want installed
+by passing the `--E|--extras` option (See [Extras](#extras) for more info)
+
+```bash
+poetry install --extras "mysql pgsql"
+poetry install -E mysql -E pgsql
+```
+
+### Options
+
+* `--no-dev`: Do not install dev dependencies.
+* `--extras (-E)`: Features to install (multiple values allowed).
+
+## update
+
+In order to get the latest versions of the dependencies and to update the `pyproject.lock` file,
+you should use the `update` command.
+
+```bash
+poetry update
+```
+
+This will resolve all dependencies of the project and write the exact versions into `pyproject.lock`.
+
+If you just want to update a few packages and not all, you can list them as such:
+
+```bash
+poetry update requests toml
+```
+
+### Options
+
+* `--dry-run` : Outputs the operations but will not execute anything (implicitly enables --verbose).
+
+## add
+
+The `add` command adds required packages to your `pyproject.toml` and installs them.
+
+If you do not specify a version constraint,
+poetry will choose a suitable one based on the available package versions.
+
+```bash
+poetry add requests pendulum
+```
+
+### Options
+
+* `--dev (-D)`: Add package as development dependency.
+* `--optional` : Add as an optional dependency.
+* `--dry-run` : Outputs the operations but will not execute anything (implicitly enables --verbose).
+
+
+## remove
+
+The `remove` command removes a package from the current
+list of installed packages
+
+```bash
+poetry remove pendulum
+```
+
+### Options
+
+* `--dev (-D)`: Removes a package from the development dependencies.
+* `--dry-run` : Outputs the operations but will not execute anything (implicitly enables --verbose).
+
+
+## show
+
+To list all of the available packages, you can use the `show` command.
+
+```bash
+poetry show
+```
+
+If you want to see the details of a certain package, you can pass the package name.
+
+```bash
+poetry show pendulum
+
+name        : pendulum
+version     : 1.4.2
+description : Python datetimes made easy
+
+dependencies:
+ - python-dateutil >=2.6.1
+ - tzlocal >=1.4
+ - pytzdata >=2017.2.2
+```
+
+### Options
+
+* `--tree`: List the dependencies as a tree.
+* `--latest (-l)`: Show the latest version.
+* `--outdated (-o)`: Show the latest version but only for packages that are outdated.
+
+
+## build
+
+The `build` command builds the source and wheels archives.
+
+```bash
+poetry build
+```
+
+Note that, at the moment, only pure python wheels are supported.
+
+### Options
+
+* `--format (-F)`: Limit the format to either wheel or sdist.
+
+## publish
+
+This command builds (if not already built) and publishes the package to the remote repository.
+
+It will automatically register the package before uploading if this is the first time it is submitted.
+
+```bash
+poetry publish
+```
+
+### Options
+
+* `--repository (-r)`: The repository to register the package to (default: `pypi`).
+Should match a repository name set by the [`config`](#config) command.
+
+
+## config
+
+The `config` command allows you to edit poetry config settings and repositories.
+
+```bash
+poetry config --list
+```
+
+### Usage
+
+````bash
+poetry config [options] [setting-key] [setting-value1] ... [setting-valueN]
+````
+
+`setting-key` is a configuration option name and `setting-value1` is a configuration value.
+
+### Modifying repositories
+
+In addition to modifying the config section,
+the config command also supports making changes to the repositories section by using it the following way:
+
+```bash
+poetry config repositories.foo https://foo.bar/simple/
+```
+
+This will set the url for repository `foo` to `https://foo.bar/simple/`.
+
+If you want to store your credentials for a specific repository, you can do so easily:
+
+```bash
+poetry config http-basic.foo username password
+```
+
+If you do not specify the password you will be prompted to write it.
+
+### Options
+
+* `--unset`: Remove the configuration element named by `setting-key`.
+* `--list`: Show the list of current config variables.
+
+## search
+
+This command searches for packages on a remote index.
+
+```bash
+poetry search requests pendulum
+```
+
+### Options
+
+* `--only-name (-N)`: Search only in name.
+
+## lock
+
+This command locks (without installing) the dependencies specified in `pyproject.toml`.
+
+```bash
+poetry lock
+```

docs/docs/libraries.md

+# Libraries
+
+This chapter will tell you how to make your library installable through Poetry.
+
+## Every project is a package
+
+As soon as you have a `pyproject.toml` in a directory, that directory is a package.
+However, to make it accessible to others you will need to package and publish it.
+
+
+## Versioning
+
+While Poetry does not enforce any convention regardind package versioning,
+it **strongly** recommends to follow [semantic versioning](https://semver.org).
+
+This has many advantages for the end users and allows them to set appropriate
+[version constraints](/versions/).
+
+## Lock file
+
+For your library, you may commit the `pyproject.lock` file if you want to.
+This can help your team to always test against the same dependency versions.
+However, this lock file will not have any effect on other projects that depend on it.
+It only has an effect on the main project.
+
+If you do not want to commit the lock file and you are using git, add it to the `.gitignore`.
+
+## Packaging
+
+Before you can actually publish your library, you will need to package it.
+
+```bash
+poetry build
+```
+
+This command will package your library in two different formats: `sdist` which is
+the source format, and `wheel` which is a `compiled` package.
+
+Once that's done you are ready to publish your library
+
+## Publishing to PyPI
+
+Alright, so now you can publish packages.
+
+Poetry will publish to [PyPI](https://pypi.org) by default. Anything that is published to PyPI
+is available automatically through Poetry. Since [pendulum](https://pypi.org/project/pendulum/)
+if on PyPI we can depend on it without having to specify any additional repositories.
+
+If we wanted to share `poetry-demo` with the Python community, we would publish on PyPI as weel.
+Doing so is really easy.
+
+```bash
+poetry publish
+```
+
+This will package and publish the library to PyPI, at the condition that you are a registered user
+and you have [configured your credentials](/repositories/#adding-credentials) properly.
+
+!!!note
+
+    The `publish` command also executes `build` by default.
+    
+    If you want to build your packages separately and later publish them,
+    just pass the `--no-build` option.
+    
+Once this is done, your library will be availbale to anyone.
+
+
+## Publishing to a private repository
+
+Sometimes, you may want to keep your library private but also being accessible to you team.
+
+In this case, you will need to use a private repository.
+
+In order to publish to a private repository, you will need to add it to your
+global list of repositories. See [Adding a repository](/repositories/#adding-a-repository)
+for more information.
+
+Once this is done, you can actually publish to it like so:
+
+```bash
+poetry publish -r my-repository
+```

docs/docs/repositories.md

+# Repositories
+
+## Using the PyPI repository
+
+By default, Poetry is configured to use the [PyPI](https://pypi.org) repository,
+for package installation and publishing.
+
+So, when you add dependencies to your project, Poetry will assume they are available
+on PyPI.
+
+This represent most cases and will likely be enough for most users.
+
+
+## Using a private repository
+
+However, at times, you may need to keep your package private while still being
+able to share it with your teammates. In this case, you will need to use a private
+repository.
+
+### Adding a repository
+
+Adding a new repository is easy with the `config` command.
+
+```bash
+poetry config repositories.foo https://foo.bar/simple/
+```
+
+This will set the url for repository `foo` to `https://foo.bar/simple/`.
+
+### Configuring credentials
+
+If you want to store your credentials for a specific repository, you can do so easily:
+
+```bash
+poetry config http-basic.foo username password
+```
+
+If you do not specify the password you will be prompted to write it.
+
+!!!note
+
+    To publish to PyPI, you can set your credentials for the repository
+    named `pypi`:
+    
+    ```bash
+    poetry config http-basic.pypi username password
+    ```
+
+### Install dependencies from a private repository
+
+Now that you can publish to your private repository, you need to be able to
+install dependencies from it.
+
+For that, you have to edit your `pyproject.toml` file, like so
+
+```toml
+[[tool.poetry.source]]
+name = "foo"
+url = "https://foo.bar/simple/"
+```
+
+From now on, Poetry will also look for packages in your private repository.

docs/docs/versions.md

+# Versions and constraints
+
+Poetry recommends following [semantic versioning](https://semver.org) but will not enforce it.
+
+## Version constraints
+
+### Caret requirements
+
+**Caret requirements** allow SemVer compatible updates to a specified version.
+An update is allowed if the new version number does not modify the left-most non-zero digit in the major, minor, patch grouping.
+In this case, if we ran `poetry update requests`, poetry would update us to version `2.14.0` if it was available,
+but would not update us to `3.0.0`.
+If instead we had specified the version string as `^0.1.13`, poetry would update to `0.1.14` but not `0.2.0`.
+`0.0.x` is not considered compatible with any other version.
+
+Here are some more examples of caret requirements and the versions that would be allowed with them:
+
+```text
+^1.2.3 := >=1.2.3 <2.0.0
+^1.2 := >=1.2.0 <2.0.0
+^1 := >=1.0.0 <2.0.0
+^0.2.3 := >=0.2.3 <0.3.0
+^0.0.3 := >=0.0.3 <0.0.4
+^0.0 := >=0.0.0 <0.1.0
+^0 := >=0.0.0 <1.0.0
+```
+
+### Tilde requirements
+
+**Tilde requirements** specify a minimal version with some ability to update.
+If you specify a major, minor, and patch version or only a major and minor version, only patch-level changes are allowed.
+If you only specify a major version, then minor- and patch-level changes are allowed.
+
+`~1.2.3` is an example of a tilde requirement.
+
+```text
+~1.2.3 := >=1.2.3 <1.3.0
+~1.2 := >=1.2.0 <1.3.0
+~1 := >=1.0.0 <2.0.0
+```
+
+### Wildcard requirements
+
+**Wildcard requirements** allow for any version where the wildcard is positioned.
+
+`*`, `1.*` and `1.2.*` are examples of wildcard requirements.
+
+```text
+* := >=0.0.0
+1.* := >=1.0.0 <2.0.0
+1.2.* := >=1.2.0 <1.3.0
+```
+
+### Inequality requirements
+
+**Inequality requirements** allow manually specifying a version range or an exact version to depend on.
+
+Here are some examples of inequality requirements:
+
+```text
+>= 1.2.0
+> 1
+< 2
+!= 1.2.3
+```
+
+### Exact requirements
+
+You can specify the exact version of a package.
+This will tell Poetry to install this version and this version only.
+If other dependencies require a different version, the solver will ultimately fail and abort any install or update procedures.
+
+#### Multiple requirements
+
+Multiple version requirements can also be separated with a comma, e.g. `>= 1.2, < 1.5`.
+
+### `git` dependencies
+
+To depend on a library located in a `git` repository,
+the minimum information you need to specify is the location of the repository with the git key:
+
+```toml
+[tool.poetry.dependencies]
+requests = { git = "https://github.com/requests/requests.git" }
+```
+
+Since we haven’t specified any other information,
+Poetry assumes that we intend to use the latest commit on the `master` branch to build our project.
+You can combine the `git` key with the `rev`, `tag`, or `branch` keys to specify something else.
+Here's an example of specifying that you want to use the latest commit on a branch named `next`:
+
+```toml
+[tool.poetry.dependencies]
+requests = { git = "https://github.com/kennethreitz/requests.git", branch = "next" }
+```
+
+### Python restricted dependencies
+
+You can also specify that a dependency should be installed only for specific Python versions:
+
+```toml
+[tool.poetry.dependencies]
+pathlib2 = { version = "^2.2", python = "~2.7" }
+```
+
+```toml
+[tool.poetry.dependencies]
+pathlib2 = { version = "^2.2", python = ["~2.7", "^3.2"] }
+```

docs/mkdocs.yml

@@ -8,8 +8,12 @@ extra:
   version: 2.0
   version: 2.0
 
 
 pages:
 pages:
-  - Home: index.md
+  - Introduction: index.md
   - Basic Usage: basic-usage.md
   - Basic Usage: basic-usage.md
+  - Libraries: libraries.md
+  - Commands: cli.md
+  - Repositories: repositories.md
+  - Versions: versions.md
 
 
 markdown_extensions:
 markdown_extensions:
   - codehilite
   - codehilite

docs/theme/main.html

@@ -9,7 +9,15 @@ title: {{ config.site_name|striptags|e }}
                 <div class="bg-white row p-l-20 p-r-20 p-b-20 p-t-5 xs-no-padding">
                 <div class="bg-white row p-l-20 p-r-20 p-b-20 p-t-5 xs-no-padding">
                     <div class="row">
                     <div class="row">
                         <div class="col-md-3 documentation-toc">
                         <div class="col-md-3 documentation-toc">
-                            {% include "toc.html" %}
+                            <ul class="current">
+                                {% set navlevel = 1 %}
+
+                                {% for nav_item in nav %}
+                                <li class="toctree-l{{ navlevel }}{% if nav_item.active and not nav_item.children %} current{%endif%}">
+                                    {% include 'nav.html' %}
+                                </li>
+                                {% endfor %}
+                            </ul>
                         </div>
                         </div>
                         <div class="col-md-9 documentation-body">
                         <div class="col-md-9 documentation-body">
                             {{page.content}}
                             {{page.content}}

docs/theme/nav.html

+{%- if nav_item.url %}
+    <a class="{% if nav_item.active%}current{%endif%}" href="{{ nav_item.url }}">{{ nav_item.title }}</a>
+{%- else %}
+    <span class="caption-text">{{ nav_item.title }}</span>
+{%- endif %}
+
+{%- if nav_item == page or nav_item.children %}
+    <ul class="subnav">
+        {%- if nav_item == page %}
+            {% include 'toc.html' %}
+        {%- endif %}
+        {%- if nav_item.children %}
+            {%- set navlevel = navlevel + 1%}
+            {%- for nav_item in nav_item.children %}
+                <li class="{% if navlevel > 2 %}toctree-l{{ navlevel }}{% endif %}{% if nav_item.active%} current{%endif%}">
+                    {% include 'nav.html' %}
+                </li>
+            {%- endfor %}
+            {%- set navlevel = navlevel - 1%}
+        {%- endif %}
+    </ul>
+{%- endif %}

docs/theme/toc.html

-<ul class="nav bs-sidenav">
-    {%- for toc_item in page.toc %}
-        <li class="main {% if toc_item.active %}active{% endif %}"><a href="{{ toc_item.url }}">{{ toc_item.title }}</a></li>
-        {%- for toc_item in toc_item.children %}
-            <li><a href="{{ toc_item.url }}">{{ toc_item.title }}</a></li>
-        {%- endfor %}
-    {%- endfor %}
-</ul>
+{% for toc_item in page.toc %}
+    <!--<li class="toctree-l{{ navlevel + 1 }}"><a href="{{ toc_item.url }}">{{ toc_item.title }}</a></li>-->
+    {% if toc_item.children %}
+        <ul>
+        {% for toc_item in toc_item.children %}
+            <li><a class="toctree-l{{ navlevel + 2 }}" href="{{ toc_item.url }}">{{ toc_item.title }}</a></li>
+        {% endfor %}
+        </ul>
+    {% endif %}
+{% endfor %}