Merge pull request #4145 from python-poetry/1.1-reorganize-docs

[1.1] Reorganize documentation

Author: sdispater

.github/workflows/docs.yml

@@ -1,6 +1,17 @@
+---
+title: "Introduction"
+draft: false
+type: docs
+layout: "single"
+
+menu:
+  docs:
+    weight: 0
+---
+
 # Introduction
 
-Poetry is a tool for dependency management and packaging in Python.
+Poetry is a tool for **dependency management** and **packaging** in Python.
 It allows you to declare the libraries your project depends on and it will manage (install/update) them for you.
 
 
@@ -9,10 +20,10 @@ It allows you to declare the libraries your project depends on and it will manag
 Poetry requires Python 2.7 or 3.5+. It is multi-platform and the goal is to make it work equally well
 on Windows, Linux and OSX.
 
-!!! note
-
-    Python 2.7 and 3.5 will no longer be supported in the next feature release (1.2).
-    You should consider updating your Python version to a supported one.
+{{% note %}}
+Python 2.7 and 3.5 will no longer be supported in the next feature release (1.2).
+You should consider updating your Python version to a supported one.
+{{% /note %}}
 
 
 ## Installation
@@ -30,10 +41,10 @@ curl -sSL https://raw.githubusercontent.com/python-poetry/poetry/master/get-poet
 (Invoke-WebRequest -Uri https://raw.githubusercontent.com/python-poetry/poetry/master/get-poetry.py -UseBasicParsing).Content | python -
 ```
 
-!!! note
-
-    You only need to install Poetry once. It will automatically pick up the current
-    Python version and use it to [create virtualenvs](/docs/managing-environments) accordingly.
+{{% note %}}
+You only need to install Poetry once. It will automatically pick up the current
+Python version and use it to [create virtualenvs]({{< relref "managing-environments" >}}) accordingly.
+{{% /note %}}
 
 The installer installs the `poetry` tool to Poetry's `bin` directory.
 On Unix it is located at `$HOME/.poetry/bin` and on Windows at `%USERPROFILE%\.poetry\bin`.
@@ -81,29 +92,29 @@ python get-poetry.py --version 0.12.0
 POETRY_VERSION=0.12.0 python get-poetry.py
 ```
 
-!!!note
+{{% note %}}
+Note that the installer does not support Poetry releases < 0.12.0.
+{{% /note %}}
 
-    Note that the installer does not support Poetry releases < 0.12.0.
+{{% note %}}
+The setup script must be able to find one of following executables in your shell's path environment:
 
-!!!note
-
-    The setup script must be able to find one of following executables in your shell's path environment:
-
-    - `python` (which can be a py3 or py2 interpreter)
-    - `python3`
-    - `py.exe -3` (Windows)
-    - `py.exe -2` (Windows)
+- `python` (which can be a py3 or py2 interpreter)
+- `python3`
+- `py.exe -3` (Windows)
+- `py.exe -2` (Windows)
+{{% /note %}}
 
 ### Alternative installation methods (not recommended)
 
-!!!note
-
-    Using alternative installation methods will make Poetry always
-    use the Python version for which it has been installed to create
-    virtualenvs.
+{{% note %}}
+Using alternative installation methods will make Poetry always
+use the Python version for which it has been installed to create
+virtualenvs.
 
-    So, you will need to install Poetry for each Python version you
-    want to use and switch between them.
+So, you will need to install Poetry for each Python version you
+want to use and switch between them.
+{{% /note %}}
 
 #### Installing with `pip`
 
@@ -113,14 +124,14 @@ Using `pip` to install Poetry is possible.
 pip install --user poetry
 ```
 
-!!!warning
-
-    Be aware that it will also install Poetry's dependencies
-    which might cause conflicts with other packages.
+{{% warning %}}
+Be aware that it will also install Poetry's dependencies
+which might cause conflicts with other packages.
+{{% /warning %}}
 
 #### Installing with `pipx`
 
-Using [`pipx`](https://github.com/cs01/pipx) to install Poetry is also possible. [pipx] is used to install Python CLI applications globally while still isolating them in virtual environments. This allows for clean upgrades and uninstalls. pipx supports Python 3.6 and later. If using an earlier version of Python, consider [pipsi](https://github.com/mitsuhiko/pipsi).
+Using [`pipx`](https://github.com/cs01/pipx) to install Poetry is also possible. `pipx` is used to install Python CLI applications globally while still isolating them in virtual environments. This allows for clean upgrades and uninstalls. pipx supports Python 3.6 and later. If using an earlier version of Python, consider [pipsi](https://github.com/mitsuhiko/pipsi).
 
 ```bash
 pipx install poetry
@@ -158,15 +169,14 @@ to `self update`.
 poetry self update 0.8.0
 ```
 
-!!!note
-
-    The `self update` command will only work if you used the recommended
-    installer to install Poetry.
-
-!!!note
-
-    If you are still on poetry version < 1.0 use `poetry self:update` instead.
+{{% note %}}
+The `self update` command will only work if you used the recommended
+installer to install Poetry.
+{{% /note %}}
 
+{{% note %}}
+If you are still on poetry version < 1.0 use `poetry self:update` instead.
+{{% /note %}}
 
 ## Enable tab completion for Bash, Fish, or Zsh
 
@@ -199,9 +209,9 @@ poetry completions zsh > ~/.zprezto/modules/completion/external/src/_poetry
 
 ```
 
-!!! note
-
-    You may need to restart your shell in order for the changes to take effect.
+{{% note %}}
+You may need to restart your shell in order for the changes to take effect.
+{{% /note %}}
 
 For `zsh`, you must then add the following line in your `~/.zshrc` before `compinit`:
 
@@ -211,7 +221,7 @@ fpath+=~/.zfunc
 
 For `oh-my-zsh`, you must then enable poetry in your `~/.zshrc` plugins
 
-```
+```text
 plugins(
 	poetry
 	...

docs/docs/index.md docs/_index.mddocs/docs/index.md renamed to docs/_index.md

@@ -1,7 +1,18 @@
+---
+title: "Basic usage"
+draft: false
+type: docs
+layout: single
+
+menu:
+  docs:
+    weight: 10
+---
+
 # Basic usage
 
 For the basic usage introduction we will be installing `pendulum`, a datetime library.
-If you have not yet installed Poetry, refer to the [Introduction](/docs/) chapter.
+If you have not yet installed Poetry, refer to the [Introduction]({{< relref "." >}} "Introduction") chapter.
 
 ## Project setup
 
@@ -77,8 +88,8 @@ It will automatically find a suitable version constraint **and install** the pac
 ## Using your virtual environment
 
 By default, poetry creates a virtual environment in `{cache-dir}/virtualenvs` (`{cache-dir}\virtualenvs` on Windows).
-You can change the [`cache-dir`](/docs/configuration/#cache-dir) value by editing the poetry config.
-Additionally, you can use the [`virtualenvs.in-project`](/docs/configuration/#virtualenvs.in-project) configuration variable
+You can change the [`cache-dir`]({{< relref "configuration#cache-dir" >}} "cache-dir configuration documentation") value by editing the poetry config.
+Additionally, you can use the [`virtualenvs.in-project`]({{< relref "configuration#virtualenvsin-project" >}} "virtualenv.in-project configuration documentation") configuration variable
 to create virtual environment within your project directory.
 
 
@@ -96,19 +107,19 @@ The easiest way to activate the virtual environment is to create a new shell wit
 To deactivate the virtual environment and exit this new shell type `exit`.
 To deactivate the virtual environment without leaving the shell use `deactivate`.
 
-!!!note
-
-	**Why a new shell?**
-	Child processes inherit their environment from their parents, but do not share
-	them. As such, any modifications made by a child process, is not persisted after
-	the child process exits. A Python application (Poetry), being a child process,
-	cannot modify the environment of the shell that it has been called from such
-	that an activated virtual environment remains active after the Poetry command
-	has completed execution.
+{{% note %}}
+**Why a new shell?**
 
-	Therefore, Poetry has to create a sub-shell with the virtual envrionment activated
-	in order for the subsequent commands to run from within the virtual environment.
+Child processes inherit their environment from their parents, but do not share
+them. As such, any modifications made by a child process, is not persisted after
+the child process exits. A Python application (Poetry), being a child process,
+cannot modify the environment of the shell that it has been called from such
+that an activated virtual environment remains active after the Poetry command
+has completed execution.
 
+Therefore, Poetry has to create a sub-shell with the virtual envrionment activated
+in order for the subsequent commands to run from within the virtual environment.
+{{% /note %}}
 
 Alternatively, to avoid creating a new shell, you can manually activate the
 virtual environment by running `source {path_to_venv}/bin/activate` (`source {path_to_venv}\Scripts\activate.bat` on Windows).
@@ -128,21 +139,21 @@ To deactivate this virtual environment simply use `deactivate`.
 In our example, we are requesting the `pendulum` package with the version constraint `^1.4`.
 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 [Dependency specification](/docs/dependency-specification) for more in-depth information on versions,
+Please read [Dependency specification]({{< relref "dependency-specification" >}} "Dependency specification documentation") for more in-depth information on versions,
 how versions relate to each other, and on the different ways you can specify dependencies.
 
 
-!!!note
+{{% note %}}
+**How does Poetry download the right files?**
 
-    **How does Poetry download the right files?**
+When you specify a dependency in `pyproject.toml`, Poetry first takes 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 back on PyPI.
 
-    When you specify a dependency in `pyproject.toml`, Poetry first takes 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 back on PyPI.
-
-    When Poetry finds the right package, it then attempts to find the best match
-    for the version constraint you have specified.
+When Poetry finds the right package, it then attempts to find the best match
+for the version constraint you have specified.
+{{% /note %}}
 
 
 ## Installing dependencies
@@ -189,9 +200,9 @@ Even if you develop alone, in six months when reinstalling the project you can f
 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.
+{{% note %}}
+For libraries it is not necessary to commit the lock file.
+{{% /note %}}
 
 ### Installing dependencies only
 
@@ -212,7 +223,7 @@ This will fetch the latest matching versions (according to your `pyproject.toml`
 and update the lock file with the new versions.
 (This is equivalent to deleting the `poetry.lock` file and running `install` again.)
 
-!!!note
-
-    Poetry will display a **Warning** when executing an install command if `poetry.lock` and `pyproject.toml`
-    are not synchronized.
+{{% note %}}
+Poetry will display a **Warning** when executing an install command if `poetry.lock` and `pyproject.toml`
+are not synchronized.
+{{% /note %}}