feat: Autogeneration of the CLI documentation.

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,21 @@
+--8<-- [start:description]
+## Description
+
+The `pixi` command is the main entry point for the Pixi CLI.
+
+--8<-- [end:description]
+
+
+--8<-- [start:example]
+## Examples
+
+Set the verbosity of pixi with the multi level flag `-v` or `--verbose`:
+
+```shell
+pixi -v command # info
+pixi -vv command # debug
+pixi -vvv command # trace
+
+pixi --verbose command # info
+```
+--8<-- [end:example]

docs/reference/cli/pixi/add.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](/docs/reference/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/init.md

@@ -0,0 +1,27 @@
+--8<-- [start:description]
+
+!!! info "Importing an environment.yml"
+    When importing an environment, the `pixi.toml` will be created with the dependencies from the environment file.
+    The `pixi.lock` will be created when you install the environment.
+    We don't support `git+` urls as dependencies for pip packages and for the `defaults` channel we use `main`, `r` and `msys2` as the default channels.
+
+
+--8<-- [end:description]
+
+
+--8<-- [start:example]
+
+## Examples
+
+```shell
+pixi init myproject
+pixi init ~/myproject
+pixi init  # Initializes directly in the current directory.
+pixi init --channel conda-forge --channel bioconda myproject
+pixi init --platform osx-64 --platform linux-64 myproject
+pixi init --import environment.yml
+pixi init --format pyproject
+pixi init --format pixi --scm gitlab
+```
+
+--8<-- [end:example]

docs/stylesheets/extra.css

@@ -94,6 +94,11 @@
   height: 100%;
 }
 
+.md-typeset table td,
+.md-typeset table th {
+  font-size: 0.8rem;
+}
+
 table code {
   white-space: nowrap;
   word-break: keep-all;

mkdocs.yml

@@ -148,7 +148,7 @@ nav:
   - Reference:
       - Pixi Manifest: reference/pixi_manifest.md
       - Pixi Configuration: reference/pixi_configuration.md
-      - CLI: reference/cli.md
+      - CLI: autogenerated/pixi.md
   - Misc:
       - Pixi vision: vision.md
       - Packaging: packaging.md

pixi.toml

@@ -74,6 +74,7 @@ test-specific-test = { cmd = "pytest", depends-on = ["build-release"] }
 # e.g. "multiple_versions_channel_1"
 update-test-channel = { cmd = "python update-channels.py", cwd = "tests/data/channels" }
 
+generate-cli-docs = "cargo run --manifest-path pixi_docs/Cargo.toml -- --output-dir docs/autogenerated"
 
 [feature.dev.dependencies]
 # Needed for the citation