feat: Autogeneration of the CLI documentation.

.github/workflows/ci.yml

@@ -119,6 +119,32 @@ jobs:
       - name: Test cargo vendor
         run: cargo vendor --locked
 
+  check-cli-docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: prefix-dev/setup-pixi@v0.8.3
+
+      - uses: Swatinem/rust-cache@v2
+        with:
+          workspaces: ". -> target/pixi"
+          key: ${{ hashFiles('pixi.lock') }}
+          save-if: ${{ github.ref == 'refs/heads/main' }}
+
+      - name: Verify CLI documentation
+        run: |
+          # Remove the generated CLI documentation to make sure we don't accidentally leave removed documentation
+          find docs/reference/cli -type f -name '*.md' -exec grep -q '<!--- This file is autogenerated. Do not edit manually! -->' {} \; -print0 | xargs -0 rm
+
+          # Regenerate CLI documentation
+          pixi run generate-cli-docs
+
+          # Check if there are any changes
+          if ! git diff --quiet; then
+            echo "Error: Generated CLI documentation differs from committed version"
+            git diff
+            exit 1
+          fi
   #
   # Run tests on important platforms.
   #

crates/pixi_config/src/lib.rs

@@ -102,15 +102,15 @@ pub struct ConfigCli {
     #[arg(long)]
     auth_file: Option<PathBuf>,
 
-    /// Specifies if we want to use uv keyring provider
+    /// Specifies whether to use the keyring to look up credentials for PyPI.
     #[arg(long)]
     pypi_keyring_provider: Option<KeyringProvider>,
 
     /// Max concurrent solves, default is the number of CPUs
     #[arg(long)]
     pub concurrent_solves: Option<usize>,
 
-    /// Max concurrent network requests, default is 50
+    /// Max concurrent network requests, default is `50`
     #[arg(long)]
     pub concurrent_downloads: Option<usize>,
 }

docs/advanced/shebang.md

@@ -4,7 +4,7 @@
 !!!warning "Only on Unix-like systems"
     The following approach only works on Unix-like systems (i.e. Linux and macOS) since Windows does not support shebang lines.
 
-For simple scripts, you can use [`pixi exec`](../reference/cli.md#exec) to run them directly without needing to take care of installing dependencies or setting up a virtual environment.
+For simple scripts, you can use [`pixi exec`](../reference/cli/pixi/exec.md) to run them directly without needing to take care of installing dependencies or setting up a virtual environment.
 This can be done by adding a [shebang line](https://en.wikipedia.org/wiki/Shebang_(Unix)) at the top of the script, which tells the system how to execute the script.
 Usually, a shebang line starts with `#!/usr/bin/env` followed by the name of the interpreter to use.
 

docs/integration/ci/github_actions.md

@@ -270,7 +270,7 @@ With `pixi exec`, you can also run a one-off command inside a temporary pixi env
 
 1. everything here will be run inside of the temporary pixi environment
 
-See [here](../../reference/cli.md#exec) for more information about `pixi exec`.
+See [here](../../reference/cli/pixi/exec.md) for more information about `pixi exec`.
 
 ### Environment activation
 

docs/integration/third_party/pixi_diff.md

@@ -15,7 +15,7 @@ With [henriklovhaug/md-tui](https://github.com/henriklovhaug/md-tui), you can ev
     pixi global install pixi-diff pixi-diff-to-markdown md-tui
     ```
 
-`pixi-diff --before pixi.lock.old --after pixi.lock.new` will output a JSON object that contains the differences between the two lockfiles similar to [`pixi update --json`](../../reference/cli.md#update).
+`pixi-diff --before pixi.lock.old --after pixi.lock.new` will output a JSON object that contains the differences between the two lockfiles similar to [`pixi update --json`](../../reference/cli/pixi/update.md).
 
 ```bash
 $ pixi-diff --before pixi.lock.old --after pixi.lock.new

docs/reference/cli/__README.md

@@ -0,0 +1,9 @@
+This directory contains the same structure as the autogenerated cli documentation.
+
+In all the autogenerated files, there are `snippets` injected like `description` and `example`.
+
+If you put a file with the same file name and path as the autogenerated companion file, the `snippets` will be injected into the file.
+
+For example, `docs/autogenerated/pixi.md` is the autogenerated file and `docs/reference/cli/pixi.md` is the injecting file.
+
+Snipped documentation can be found here: https://facelessuser.github.io/pymdown-extensions/extensions/snippets/

docs/reference/cli/pixi.md

@@ -0,0 +1,60 @@
+<!--- This file is autogenerated. Do not edit manually! -->
+# <code>pixi</code>
+
+--8<-- "docs/reference/cli/pixi_extender.md:description"
+
+## Usage
+```
+pixi [OPTIONS] <COMMAND>
+```
+
+## Subcommands
+| Command | Description |
+|---------|-------------|
+| [`init`](pixi/init.md) | Creates a new workspace |
+| [`add`](pixi/add.md) | Adds dependencies to the workspace |
+| [`remove`](pixi/remove.md) | Removes dependencies from the workspace |
+| [`install`](pixi/install.md) | Install an environment, both updating the lockfile and installing the environment |
+| [`update`](pixi/update.md) | The `update` command checks if there are newer versions of the dependencies and updates the `pixi.lock` file and environments accordingly |
+| [`upgrade`](pixi/upgrade.md) | Checks if there are newer versions of the dependencies and upgrades them in the lockfile and manifest file |
+| [`lock`](pixi/lock.md) | Solve environment and update the lock file without installing the environments |
+| [`run`](pixi/run.md) | Runs task in the pixi environment |
+| [`exec`](pixi/exec.md) | Run a command and install it in a temporary environment |
+| [`shell`](pixi/shell.md) | Start a shell in a pixi environment, run `exit` to leave the shell |
+| [`shell-hook`](pixi/shell-hook.md) | Print the pixi environment activation script |
+| [`project`](pixi/project.md) | Modify the project configuration file through the command line |
+| [`task`](pixi/task.md) | Interact with tasks in the workspace |
+| [`list`](pixi/list.md) | List project's packages |
+| [`tree`](pixi/tree.md) | Show a tree of project dependencies |
+| [`global`](pixi/global.md) | Subcommand for global package management actions |
+| [`auth`](pixi/auth.md) | Login to prefix.dev or anaconda.org servers to access private channels |
+| [`config`](pixi/config.md) | Configuration management |
+| [`info`](pixi/info.md) | Information about the system, project and environments for the current machine |
+| [`upload`](pixi/upload.md) | Upload a conda package |
+| [`search`](pixi/search.md) | Search a conda package |
+| [`self-update`](pixi/self-update.md) | Update pixi to the latest version or a specific version |
+| [`clean`](pixi/clean.md) | Cleanup the environments |
+| [`completion`](pixi/completion.md) | Generates a completion script for a shell |
+| [`build`](pixi/build.md) | Workspace configuration |
+
+
+## Options
+- <a id="option-version" href="#option-version">`--version (-V)`</a>
+: Display version information
+
+## Global Options
+- <a id="arg---color" href="#arg---color">`--color <COLOR>`</a>
+:  Whether the log needs to be colored
+<br>**env**: `PIXI_COLOR`
+<br>**default**: `auto`
+<br>**options**: `always`, `never`, `auto`
+- <a id="arg---no-progress" href="#arg---no-progress">`--no-progress`</a>
+:  Hide all progress bars, always turned on if stderr is not a terminal
+<br>**env**: `PIXI_NO_PROGRESS`
+<br>**default**: `false`
+- <a id="arg---quiet" href="#arg---quiet">`--quiet (-q)`</a>
+:  Decrease logging verbosity
+- <a id="arg---verbose" href="#arg---verbose">`--verbose (-v)`</a>
+:  Increase logging verbosity
+
+--8<-- "docs/reference/cli/pixi_extender.md:example"

docs/reference/cli/pixi/add.md

@@ -0,0 +1,131 @@
+<!--- This file is autogenerated. Do not edit manually! -->
+# <code>[pixi](../pixi.md) add</code>
+
+## About
+Adds dependencies to the workspace
+
+--8<-- "docs/reference/cli/pixi/add_extender.md:description"
+
+## Usage
+```
+pixi add [OPTIONS] <SPECS>...
+```
+
+## Arguments
+- <a id="arg-<SPECS>" href="#arg-<SPECS>">`<SPECS>`</a>
+:  The dependencies as names, conda MatchSpecs or PyPi requirements
+<br>**required**: `true`
+
+## Options
+- <a id="arg---auth-file" href="#arg---auth-file">`--auth-file <AUTH_FILE>`</a>
+:  Path to the file containing the authentication token
+- <a id="arg---branch" href="#arg---branch">`--branch <BRANCH>`</a>
+:  The git branch
+- <a id="arg---build" href="#arg---build">`--build`</a>
+:  The specified dependencies are build dependencies. Conflicts with `host` and `pypi`
+- <a id="arg---concurrent-downloads" href="#arg---concurrent-downloads">`--concurrent-downloads <CONCURRENT_DOWNLOADS>`</a>
+:  Max concurrent network requests, default is `50`
+- <a id="arg---concurrent-solves" href="#arg---concurrent-solves">`--concurrent-solves <CONCURRENT_SOLVES>`</a>
+:  Max concurrent solves, default is the number of CPUs
+- <a id="arg---editable" href="#arg---editable">`--editable`</a>
+:  Whether the pypi requirement should be editable
+- <a id="arg---feature" href="#arg---feature">`--feature (-f) <FEATURE>`</a>
+:  The feature for which the dependency should be modified
+<br>**default**: `default`
+- <a id="arg---frozen" href="#arg---frozen">`--frozen`</a>
+:  Install the environment as defined in the lockfile, doesn't update lockfile if it isn't up-to-date with the manifest file
+<br>**env**: `PIXI_FROZEN`
+- <a id="arg---git" href="#arg---git">`--git (-g) <GIT>`</a>
+:  The git url to use when adding a git dependency
+- <a id="arg---host" href="#arg---host">`--host`</a>
+:  The specified dependencies are host dependencies. Conflicts with `build` and `pypi`
+- <a id="arg---locked" href="#arg---locked">`--locked`</a>
+:  Check if lockfile is up-to-date before installing the environment, aborts when lockfile isn't up-to-date with the manifest file
+<br>**env**: `PIXI_LOCKED`
+- <a id="arg---no-install" href="#arg---no-install">`--no-install`</a>
+:  Don't modify the environment, only modify the lock-file
+- <a id="arg---no-lockfile-update" href="#arg---no-lockfile-update">`--no-lockfile-update`</a>
+:  Don't update lockfile, implies the no-install as well
+- <a id="arg---platform" href="#arg---platform">`--platform (-p) <PLATFORMS>`</a>
+:  The platform(s) for which the dependency should be modified
+- <a id="arg---pypi" href="#arg---pypi">`--pypi`</a>
+:  The specified dependencies are pypi dependencies. Conflicts with `host` and `build`
+- <a id="arg---pypi-keyring-provider" href="#arg---pypi-keyring-provider">`--pypi-keyring-provider <PYPI_KEYRING_PROVIDER>`</a>
+:  Specifies whether to use the keyring to look up credentials for PyPI
+<br>**options**: `disabled`, `subprocess`
+- <a id="arg---rev" href="#arg---rev">`--rev <REV>`</a>
+:  The git revision
+- <a id="arg---revalidate" href="#arg---revalidate">`--revalidate`</a>
+:  Run the complete environment validation. This will reinstall a broken environment
+- <a id="arg---subdir" href="#arg---subdir">`--subdir (-s) <SUBDIR>`</a>
+:  The subdirectory of the git repository to use
+- <a id="arg---tag" href="#arg---tag">`--tag <TAG>`</a>
+:  The git tag
+- <a id="arg---tls-no-verify" href="#arg---tls-no-verify">`--tls-no-verify`</a>
+:  Do not verify the TLS certificate of the server
+
+## Global Options
+- <a id="arg---manifest-path" href="#arg---manifest-path">`--manifest-path <MANIFEST_PATH>`</a>
+:  The path to `pixi.toml`, `pyproject.toml`, or the project directory
+
+## Description
+Adds dependencies to the workspace
+
+The dependencies should be defined as MatchSpec for conda package, or a PyPI
+requirement for the `--pypi` dependencies. If no specific version is
+provided, the latest version compatible with your project will be chosen
+automatically or a * will be used.
+
+Example usage:
+
+- `pixi add python=3.9`: This will select the latest minor version that
+  complies with 3.9.*, i.e., python version 3.9.0, 3.9.1, 3.9.2, etc.
+- `pixi add python`: In absence of a specified version, the latest version
+  will be chosen. For instance, this could resolve to python version
+  3.11.3.* at the time of writing.
+
+Adding multiple dependencies at once is also supported:
+
+- `pixi add python pytest`: This will add both `python` and `pytest` to the
+  project's dependencies.
+
+The `--platform` and `--build/--host` flags make the dependency target
+specific.
+
+- `pixi add python --platform linux-64 --platform osx-arm64`: Will add the
+  latest version of python for linux-64 and osx-arm64 platforms.
+- `pixi add python --build`: Will add the latest version of python for as a
+  build dependency.
+
+Mixing `--platform` and `--build`/`--host` flags is supported
+
+The `--pypi` option will add the package as a pypi dependency. This cannot
+be mixed with the conda dependencies
+
+- `pixi add --pypi boto3`
+- `pixi add --pypi "boto3==version"`
+
+If the project manifest is a `pyproject.toml`, adding a pypi dependency will
+add it to the native pyproject `project.dependencies` array or to the native
+`dependency-groups` table if a feature is specified:
+
+- `pixi add --pypi boto3` will add `boto3` to the `project.dependencies`
+  array
+- `pixi add --pypi boto3 --feature aws` will add `boto3` to the
+  `dependency-groups.aws` array
+
+Note that if `--platform` or `--editable` are specified, the pypi dependency
+will be added to the `tool.pixi.pypi-dependencies` table instead as native
+arrays have no support for platform-specific or editable dependencies.
+
+These dependencies will then be read by pixi as if they had been added to
+the pixi `pypi-dependencies` tables of the default or of a named feature.
+
+The versions will be automatically added with a pinning strategy based on
+semver or the pinning strategy set in the config. There is a list of
+packages that are not following the semver versioning scheme but will use
+the minor version by default:
+Python, Rust, Julia, GCC, GXX, GFortran, NodeJS, Deno, R, R-Base, Perl
+
+
+--8<-- "docs/reference/cli/pixi/add_extender.md:example"

docs/reference/cli/pixi/add_extender.md

@@ -0,0 +1,75 @@
+
+--8<-- [start:example]
+
+## Examples
+
+```shell
+pixi add numpy # (1)!
+pixi add numpy pandas "pytorch>=1.8" # (2)!
+pixi add "numpy>=1.22,<1.24" # (3)!
+pixi add --manifest-path ~/myproject/pixi.toml numpy # (4)!
+pixi add --host "python>=3.9.0" # (5)!
+pixi add --build cmake # (6)!
+pixi add --platform osx-64 clang # (7)!
+pixi add --no-install numpy # (8)!
+pixi add --no-lockfile-update numpy # (9)!
+pixi add --feature featurex numpy # (10)!
+pixi add --git https://github.com/wolfv/pixi-build-examples boost-check # (11)!
+pixi add --git https://github.com/wolfv/pixi-build-examples --branch main --subdir boost-check boost-check # (12)!
+pixi add --git https://github.com/wolfv/pixi-build-examples --tag v0.1.0 boost-check # (13)!
+pixi add --git https://github.com/wolfv/pixi-build-examples --rev e50d4a1 boost-check # (14)!
+
+# Add a pypi dependency
+pixi add --pypi requests[security] # (15)!
+pixi add --pypi Django==5.1rc1 # (16)!
+pixi add --pypi "boltons>=24.0.0" --feature lint # (17)!
+pixi add --pypi "boltons @ https://files.pythonhosted.org/packages/46/35/e50d4a115f93e2a3fbf52438435bb2efcf14c11d4fcd6bdcd77a6fc399c9/boltons-24.0.0-py3-none-any.whl" # (18)!
+pixi add --pypi "exchangelib @ git+https://github.com/ecederstrand/exchangelib" # (19)!
+pixi add --pypi "project @ file:///absolute/path/to/project" # (20)!
+pixi add --pypi "project@file:///absolute/path/to/project" --editable # (21)!
+pixi add --git https://github.com/mahmoud/boltons.git boltons --pypi # (22)!
+pixi add --git https://github.com/mahmoud/boltons.git boltons --branch main --pypi # (23)!
+pixi add --git https://github.com/mahmoud/boltons.git boltons --rev e50d4a1 --pypi # (24)!
+pixi add --git https://github.com/mahmoud/boltons.git boltons --tag v0.1.0 --pypi # (25)!
+pixi add --git https://github.com/mahmoud/boltons.git boltons --tag v0.1.0 --pypi --subdir boltons # (26)!
+```
+
+1. This will add the `numpy` package to the project with the latest available for the solved environment.
+2. This will add multiple packages to the project solving them all together.
+3. This will add the `numpy` package with the version constraint.
+4. This will add the `numpy` package to the project of the manifest file at the given path.
+5. This will add the `python` package as a host dependency. There is currently no different behavior for host dependencies.
+6. This will add the `cmake` package as a build dependency. There is currently no different behavior for build dependencies.
+7. This will add the `clang` package only for the `osx-64` platform.
+8. This will add the `numpy` package to the manifest and lockfile, without installing it in an environment.
+9. This will add the `numpy` package to the manifest without updating the lockfile or installing it in the environment.
+10. This will add the `numpy` package in the feature `featurex`.
+11. This will add the `boost-check` source package to the dependencies from the git repository.
+12. This will add the `boost-check` source package to the dependencies from the git repository using `main` branch and the `boost-check` folder in the repository.
+13. This will add the `boost-check` source package to the dependencies from the git repository using `v0.1.0` tag.
+14. This will add the `boost-check` source package to the dependencies from the git repository using `e50d4a1` revision.
+15. This will add the `requests` package as `pypi` dependency with the `security` extra.
+16. This will add the `pre-release` version of `Django` to the project as a `pypi` dependency.
+17. This will add the `boltons` package in the feature `lint` as `pypi` dependency.
+18. This will add the `boltons` package with the given `url` as `pypi` dependency.
+19. This will add the `exchangelib` package with the given `git` url as `pypi` dependency.
+20. This will add the `project` package with the given `file` url as `pypi` dependency.
+21. This will add the `project` package with the given `file` url as an `editable` package as `pypi` dependency.
+22. This will add the `boltons` package with the given `git` url as `pypi` dependency.
+23. This will add the `boltons` package with the given `git` url and `main` branch as `pypi` dependency.
+24. This will add the `boltons` package with the given `git` url and `e50d4a1` revision as `pypi` dependency.
+25. This will add the `boltons` package with the given `git` url and `v0.1.0` tag as `pypi` dependency.
+26. This will add the `boltons` package with the given `git` url, `v0.1.0` tag and the `boltons` folder in the repository as `pypi` dependency.
+
+!!! tip
+    If you want to use a non default pinning strategy, you can set it using [pixi's configuration](../../pixi_configuration.md#pinning-strategy).
+    ```
+    pixi config set pinning-strategy no-pin --global
+    ```
+    The default is `semver` which will pin the dependencies to the latest major version or minor for `v0` versions.
+!!! note
+    There is an exception to this rule when you add a package we defined as non `semver`, then we'll use the `minor` strategy.
+    These are the packages we defined as non `semver`:
+    Python, Rust, Julia, GCC, GXX, GFortran, NodeJS, Deno, R, R-Base, Perl
+
+--8<-- [end:example]

docs/reference/cli/pixi/auth.md

@@ -0,0 +1,21 @@
+<!--- This file is autogenerated. Do not edit manually! -->
+# <code>[pixi](../pixi.md) auth</code>
+
+## About
+Login to prefix.dev or anaconda.org servers to access private channels
+
+--8<-- "docs/reference/cli/pixi/auth_extender.md:description"
+
+## Usage
+```
+pixi auth <COMMAND>
+```
+
+## Subcommands
+| Command | Description |
+|---------|-------------|
+| [`login`](auth/login.md) | Store authentication information for a given host |
+| [`logout`](auth/logout.md) | Remove authentication information for a given host |
+
+
+--8<-- "docs/reference/cli/pixi/auth_extender.md:example"