Reorganize documentation

python-poetry · Jun 4, 2021 · 8e4b7e3 · 8e4b7e3
1 parent 6bd4f1a
commit 8e4b7e3
Show file tree

Hide file tree

Showing 19 changed files with 650 additions and 369 deletions.
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
diff --git a/docs/docs/index.md → docs/_index.md b/docs/docs/index.md → docs/_index.md
@@ -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,11 +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
 
@@ -29,10 +39,10 @@ curl -sSL https://raw.githubusercontent.com/python-poetry/poetry/master/install-
 (Invoke-WebRequest -Uri https://raw.githubusercontent.com/python-poetry/poetry/master/install-poetry.py -UseBasicParsing).Content | python -
 ```
 
-!!!warning
-
-    The previous `get-poetry.py` installer is now deprecated, if you are currently using it
-    you should migrate to the new, supported, `install-poetry.py` installer.
+{{% warning %}}
+The previous `get-poetry.py` installer is now deprecated, if you are currently using it
+you should migrate to the new, supported, `install-poetry.py` installer.
+{{% /warning %}}
 
 The installer installs the `poetry` tool to Poetry's `bin` directory. This location depends on your system:
 
@@ -89,9 +99,9 @@ You can also install Poetry for a `git` repository by using the `--git` option:
 python install-poetry.py --git https://github.com/python-poetry/poetry.git@master
 ````
 
-!!!note
-
-    Note that the installer does not support Python < 3.6.
+{{% note %}}
+Note that the installer does not support Python < 3.6.
+{{% /note %}}
 
 
 ### Alternative installation methods
@@ -123,25 +133,24 @@ 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 %}}
 
 ## Updating `poetry`
 
 Updating Poetry to the latest stable version is as simple as calling the `self update` command.
 
-!!!warning
-
-    Poetry versions installed using the now deprecated `get-poetry.py` installer will not be able to use this
-    command to update to 1.2 releases or later. Migrate to using the `install-poetry.py` installer or `pipx`.
-
 ```bash
 poetry self update
 ```
 
+{{% warning %}}
+Poetry versions installed using the now deprecated `get-poetry.py` installer will not be able to use this
+command to update to 1.2 releases or later. Migrate to using the `install-poetry.py` installer or `pipx`.
+{{% /warning %}}
+
 If you want to install pre-release versions, you can use the `--preview` option.
 
 ```bash
@@ -187,9 +196,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`:
 
@@ -199,7 +208,7 @@ fpath+=~/.zfunc
 
 For `oh-my-zsh`, you must then enable poetry in your `~/.zshrc` plugins
 
-```
+```text
 plugins(
 	poetry
 	...

diff --git a/docs/docs/basic-usage.md → docs/basic-usage.md b/docs/docs/basic-usage.md → docs/basic-usage.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 "docs" >}} "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#virtualenvs.in-project" >}} "#virtualenvs.in-project configuration documentation") configuration variable
 to create virtual environment within your project directory.
 
 
@@ -96,18 +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
+{{% note %}}
+**Why a new shell?**
 
-	**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.
+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 environment activated
-	in order for the subsequent commands to run from within the virtual environment.
+Therefore, Poetry has to create a sub-shell with the virtual environment 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
@@ -116,33 +128,33 @@ To get the path to your virtual environment run `poetry env info --path`.
 You can also combine these into a nice one-liner, `source $(poetry env info --path)/bin/activate`
 To deactivate this virtual environment simply use `deactivate`.
 
-|                   | POSIX Shell                                       | Windows                                     | Exit/Deactivate |
-|-------------------|---------------------------------------------------|---------------------------------------------|-----------------|
-| New Shell         | `poetry shell`                                    | `poetry shell`                              | `exit`          |
-| Manual Activation | `source {path_to_venv}/bin/activate`              | `{path_to_venv}\Scripts\activate.bat`       | `deactivate`    |
-| One-liner         | ```source `poetry env info --path`/bin/activate```|                                             | `deactivate`    |
+|                   | POSIX Shell                                        | Windows                               | Exit/Deactivate |
+| ----------------- | -------------------------------------------------- | ------------------------------------- | --------------- |
+| New Shell         | `poetry shell`                                     | `poetry shell`                        | `exit`          |
+| Manual Activation | `source {path_to_venv}/bin/activate`               | `{path_to_venv}\Scripts\activate.bat` | `deactivate`    |
+| One-liner         | ```source `poetry env info --path`/bin/activate``` |                                       | `deactivate`    |
 
 
 ### Version constraints
 
 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
-
-    **How does Poetry download the right files?**
+{{% note %}}
+**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 +201,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 +224,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 %}}