From 095b02b983e2dcfb46421e1aa8426b620f6e0c84 Mon Sep 17 00:00:00 2001
From: Armin Ronacher <armin.ronacher@active-4.com>
Date: Sun, 14 May 2023 02:15:53 +0200
Subject: [PATCH] More docs

---
 .python-version         |   1 +
 README.md               | 139 ++--------------------------------------
 docs/guide/config.md    |   2 +-
 docs/guide/deps.md      |  57 ++++++++++++++++
 docs/guide/pyproject.md |   2 +-
 docs/guide/sync.md      |  78 ++++++++++++++++++++++
 mkdocs.yml              |   4 +-
 7 files changed, 147 insertions(+), 136 deletions(-)
 create mode 100644 .python-version
 create mode 100644 docs/guide/deps.md
 create mode 100644 docs/guide/sync.md

diff --git a/.python-version b/.python-version
new file mode 100644
index 0000000000..371cfe355d
--- /dev/null
+++ b/.python-version
@@ -0,0 +1 @@
+3.11.1
diff --git a/README.md b/README.md
index cf0115c3bb..0bb20f0b39 100644
--- a/README.md
+++ b/README.md
@@ -17,6 +17,12 @@ an exploration, and it's far from perfect. Thus also the question:
   <p><em>Click on the thumbnail to watch a 9 minute introduction video</em></p>
 </div>
 
+Learn more:
+
+* [Documentation](https://mitsuhiko.github.io/rye)
+* [Issue Tracker](https://github.com/mitsuhiko/issues)
+* [Discussions](https://github.com/mitsuhiko/discussions)
+
 ## Installation
 
 Rye is built in Rust. There is no binary distribution yet, it only works on Linux
@@ -56,11 +62,6 @@ pick up the right Python without manually activating the virtualenv, you can add
 of a rye managed project, the regular Python is picked up automatically. For the global
 tool installation you need to add the shims to the path.
 
-## Deinstallation
-
-If you no longer want anything to do with rye, all you need to delete is the `~/.rye`
-folder.  Everything that it has downloaded / created is placed in there.
-
 ## Some of the things it does
 
 It automatically installs and manages Python:
@@ -123,91 +124,6 @@ To understand why things are the way they are:
   shims to your shell and you can run `python` and it will automatically always
   operate in the right project.
 
-## What Could Be?
-
-There are a few shortcomings in the Python packaging world, largely as a result of
-lack of standardization. Here is what this project ran into over the years:
-
-- **No Python Binary Distributions:** CPython builds from python.org are completely
-  inadequate. On some platforms you only get an .msi installer, on some you
-  literally only get tarballs. The various Python distributions that became popular
-  over the years are diverging greatly and cause all kinds of nonsense downstream.
-  This is why this Project uses the indygreg standalone builds. I hope that with
-  time someone will start distributing well maintained and reliable Python builds
-  to replace the mess we are dealing with today.
-
-- **No Dev Dependencies:** Rye currently needs a custom section in the `pyproject.toml`
-  to represent dev dependencies. There is no standard in the ecosystem for this. It
-  really should be added.
-
-- **No Local Dependency Overlays:** There is no standard for how to represent local
-  dependencies. Rust for this purpose has something like `{ path = "../foo" }`
-  which allows both remote and local references to co-exist and it rewrites them
-  on publish.
-
-- **No Exposed Pip:** pip is intentionally not exposed. If you were to install something
-  into the virtualenv, it disappears next time you sync. If you symlink `rye` to
-  `~/.rye/shims/pip` you can get access to pip without installing it into the
-  virtualenv. There be dragons.
-
-- **No Workspace Spec:** for monorepos and things of that nature, the Python ecosystem
-  would need a definition of workspaces. Today that does not exist which forces every
-  tool to come up with it's own solutions to this problem.
-
-- **No Basic Script Section:** There should be a standard in `pyproject.toml` to
-  represent scripts like `rye` does in `rye.tools.scripts`.
-
-## Adding Dependencies
-
-To add a new dependency run `rye add` with the name of the package that you want to
-install. Additionally a proprietary extension to `pyproject.toml` exists to add
-development only packages. For those add `--dev`.
-
-```shell
-$ rye add "flask>=2.0"
-$ rye add --dev black
-```
-
-Adding dependencies will not directly install them. To install them run `rye sync` again.
-
-## Workspaces
-
-To have multiple projects share the same virtualenv, it's possible to declare workspaces
-in the `pyproject.toml`:
-
-```toml
-[tool.rye.workspace]
-members = ["foo-*"]
-```
-
-When `rye sync` is run in a workspace, then all packages are installed at all times. This
-also means that they can inter-depend as they will all be installed editable by default.
-
-## Lockfiles
-
-Rye does not try to re-invent the world (yet!). This means it uses `pip-tools` behind
-the scenes automatically. As neither `pip` nor `pip-tools` provide lockfiles today
-Rye uses generated `requirements.txt` files as replacement. Whenever you run
-`rye sync` it updates the `requirements.lock` and `requirements-dev.lock` files
-automatically.
-
-## Scripts
-
-`rye run` can be used to invoke a binary from the virtualenv or a configured script.
-Rye allows you to define basic scripts in the `pyproject.toml` in the `tool.rye.scripts`
-section:
-
-```toml
-[tool.rye.scripts]
-serve = "python -m http.server 8000"
-```
-
-They are only available via `rye run <script_name>`. Each script can either be a string or an
-array where each item is an argument to the script. The scripts will be run with the
-virtualenv activated.
-
-To see what's available, run `rye run` without arguments and it will list all scripts.
-
 ## Python Distributions
 
 Rye does not use system python installations. Instead it uses Gregory Szorc's standalone
@@ -216,23 +132,6 @@ This is done to create a unified experience of Python installations and to avoid
 incompatibilities created by different Python distributions. Most importantly this also
 means you never need to compile a Python any more, it just downloads prepared binaries.
 
-## Managing Python Toolchains
-
-You can register custom Python toolchains with `rye toolchain register`:
-
-```
-$ rye toolchain register ~/Downloads/pypy3.9-v7.3.11-macos_arm64/bin/python
-Registered /Users/mitsuhiko/Downloads/pypy3.9-v7.3.11-macos_arm64/bin/python as pypy@3.9.16
-```
-
-Afterwards you can pin it, in this case with `rye pin pypy@3.9.16`. The auto detection of
-the name might not be great, in which case you can provide an explicit name with `--name`.
-To remove downloaded or linked toolchains, you can use the `rye toolchain remove` command.
-To list what's available, use `rye toolchain list`.
-
-Additionally, you can view the list of downloadable Python toolchains with the command 
-`rye toolchain list --include-downloadable`.
-
 ## Global Tools
 
 If you want tools to be installed into isolated virtualenvs (like pipsi and pipx), you
@@ -254,30 +153,4 @@ $ pycowsay Wow
 
 To uninstall run `rye uninstall pycowsay` again.
 
-## Using The Virtualenv
-
-There are two ways to use the virtual environment. One is to just activate it like you
-would do normally:
-
-```shell
-$ . .venv/bin/activate
-```
-
-The other is to use `rye run <script>` to run a script (installed into `.venv/bin`) in
-the context of the virtual environment. This for instance can be used to run black:
-
-```shell
-$ rye add --dev black
-$ rye sync
-$ rye run black .
-```
-
-## Updating Rye
-
-To update rye, you can use this command:
-
-```
-$ rye self update
-```
-
 License: MIT
diff --git a/docs/guide/config.md b/docs/guide/config.md
index e8ce8444e4..3983d5cb22 100644
--- a/docs/guide/config.md
+++ b/docs/guide/config.md
@@ -54,4 +54,4 @@ toolchain = "cpython@3.11.1"
 
 ## Per Project Config
 
-For the project specific `pyproject.toml` config see [pyproject.toml](pyproject).
+For the project specific `pyproject.toml` config see [pyproject.toml](pyproject.md).
diff --git a/docs/guide/deps.md b/docs/guide/deps.md
new file mode 100644
index 0000000000..810c78ce9a
--- /dev/null
+++ b/docs/guide/deps.md
@@ -0,0 +1,57 @@
+# Dependencies
+
+Dependencies are declared in [pyproject.toml](pyproject.md) however adding them can be
+simplified with the `rye add` command.  In the most simple invocation it adds a regular
+dependency, but it can be customized.
+
+## Adding Basic Dependency
+
+To add a regular dependency just invoke `rye add` with the name of the Python package:
+
+```
+rye add Flask
+```
+
+If you also want to define a version, use a [PEP 508](https://peps.python.org/pep-0508/)
+requirement:
+
+```
+rye add "Flask>=2.0"
+```
+
+For extra/feature depedencies you can either use PEP 508 syntax or use `--features`:
+
+```
+rye add "Flask[dotenv]"
+rye add Flask --features=dotenv
+```
+
+These dependencies are stored in [`project.dependencies`](pyproject.md#projectdependencies).
+
+## Development Dependencies
+
+For dependencies that should only be installed during development pass `--dev`
+
+```
+rye add --dev black
+```
+
+These dependencies are stored in the non-standard
+[`tool.rye.dev-dependencies`](pyproject.md#toolryedev-dependencies) key.
+
+## Git / Local Dependencies
+
+To add a local or git dependency, you can pass additional parameters like `--path`
+or `--git`:
+
+```
+rye add Flask --git=https://github.com/pallets/flask
+rye add My-Utility --path ./my-utility
+```
+
+Note that when adding such dependencies, it's necessary to also provide the name
+of the package.  Additionally for git dependencies all kinds of extra parameters
+such as `--tag`, `--rev` or `--branch` are supported.
+
+When working with local dependencies it's strongly encouraged to configure a
+[workspace](pyproject.md#toolryeworkspace).
diff --git a/docs/guide/pyproject.md b/docs/guide/pyproject.md
index 35aa409bde..32e58e89b6 100644
--- a/docs/guide/pyproject.md
+++ b/docs/guide/pyproject.md
@@ -1,4 +1,4 @@
-# pyproject.toml
+# Python Project (`pyproject.toml`)
 
 Rye tries to avoid a lot of proprietary configuration in the `pyproject.toml` file but a bit
 is necessary.  Here are the most important keys that Rye expects:
diff --git a/docs/guide/sync.md b/docs/guide/sync.md
new file mode 100644
index 0000000000..fed2c5d6de
--- /dev/null
+++ b/docs/guide/sync.md
@@ -0,0 +1,78 @@
+# Synching and Locking
+
+Rye currently uses [pip-tools](https://github.com/jazzband/pip-tools) to download and install
+dependencies.  For this purpose it creates two "lockfiles" (called `requirements.lock` and
+`requirements-dev.lock`).  These are not real lockfiles but they fulfill a similar purpose
+until a better solution has been implemented.
+
+Whenever `rye sync` is called, it will update lockfiles as well as the virtualenv.  If you only
+want to update the lockfiles, then `rye lock` can be used.
+
+## Lock
+
+When locking, some options can be provided to change the locking behavior.  These flags are
+also all available on `rye sync`.
+
+### `--update` / `--update-all`
+
+Updates a specific or all requirements to the latest and greatest version.  Without this flag
+a dependency will only be updated if necessary.
+
+```
+rye lock --update-all
+```
+
+### `--features` / `--all-features`
+
+Python packages can have extra dependencies.  By default the local package that is installed
+will only be installed with the default features.  If for instance you have an extra dependency
+this will only be installed if the feature is enabled.
+
+```
+rye add --optional=web flask
+rye lock --features=web
+```
+
+When working with workspaces, the package name needs to be prefixed with a slash:
+
+```
+rye lock --features=package-name/feature-name
+```
+
+The `--features` parameter can be passed multiple times and features can also be comma
+separated.  To turn on all features, the `--all-features` parameter can be used.
+
+```
+rye lock --all-features
+```
+
+### `--pre`
+
+By default updates and version resolution will not consider pre-releases of packages.  If you
+do want to include those, pass `--pre`
+
+```
+rye lock Flask --pre
+```
+
+## Sync
+
+Synching takes the same parameters as `lock` and then some.  Sync will usually first do what
+`lock` does and then use the lockfiles to update the virtualenv.
+
+### `--no-lock`
+
+To prevent the lock step from automatically running, pass `--no-lock`.
+
+```
+rye sync --no-lock
+```
+
+### `--no-dev`
+
+Only sync based on the production lockfile (`requirements.lock`) instead of the development
+lockfile (`requirements-dev.lock`).
+
+```
+rye sync --no-dev
+```
diff --git a/mkdocs.yml b/mkdocs.yml
index cbfa2a87fe..5fb277e9cf 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -11,7 +11,9 @@ nav:
     - Installation: guide/installation.md
     - Basics: guide/basics.md
     - Configuration: guide/config.md
-    - pyproject.toml: guide/pyproject.md
+    - Python Project: guide/pyproject.md
+    - Synching and Locking: guide/sync.md
+    - Dependencies: guide/deps.md
     - Toolchains: guide/toolchains.md
     - Tools: guide/tools.md
   - Philosophy: philosophy.md