docs: split options into headings

.github/workflows/ci.yml

@@ -131,21 +131,26 @@ jobs:
           key: ${{ hashFiles('pixi.lock') }}
           save-if: ${{ github.ref == 'refs/heads/main' }}
 
-      - name: Verify CLI documentation
+      - name: Remove the generated 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
+      - name: Regenerate CLI documentation
+        run: |
           pixi run generate-cli-docs
 
-          # Check if there are any changes
+      - name: Check if there are any changes
+        run: |
           if ! git diff --quiet; then
             echo "Error: Generated CLI documentation differs from committed version"
             echo "Please run 'pixi run generate-cli-docs' to regenerate the documentation and commit the changes."
             git diff
             exit 1
           fi
+
+      - name: Lint pixi_docs
+        run: |
+          pixi run lint-pixi_docs
   #
   # Run tests on important platforms.
   #

docs/reference/cli/pixi.md

@@ -38,25 +38,21 @@ pixi [OPTIONS] <COMMAND>
 | [`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---help" href="#arg---help">`--help (-h)`</a>
+:  Display help information
+- <a id="arg---verbose" href="#arg---verbose">`--verbose (-v)`</a>
+:  Increase logging verbosity (-v for warnings, -vv for info, -vvv for debug, -vvvv for trace)
+- <a id="arg---quiet" href="#arg---quiet">`--quiet (-q)`</a>
+:  Decrease logging verbosity (quiet mode)
 - <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---help" href="#arg---help">`--help (-h)`</a>
-:  Display help information
 - <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 (quiet mode)
-- <a id="arg---verbose" href="#arg---verbose">`--verbose (-v)`</a>
-:  Increase logging verbosity (-v for warnings, -vv for info, -vvv for debug, -vvvv for trace)
 
 --8<-- "docs/reference/cli/pixi_extender.md:example"

docs/reference/cli/pixi/add.md

@@ -17,48 +17,52 @@ pixi add [OPTIONS] <SPECS>...
 <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---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---pypi" href="#arg---pypi">`--pypi`</a>
+:  The specified dependencies are pypi dependencies. Conflicts with `host` and `build`
+- <a id="arg---platform" href="#arg---platform">`--platform (-p) <PLATFORMS>`</a>
+:  The platform(s) for which the dependency should be modified
 - <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---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---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---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---revalidate" href="#arg---revalidate">`--revalidate`</a>
+:  Run the complete environment validation. This will reinstall a broken environment
+- <a id="arg---editable" href="#arg---editable">`--editable`</a>
+:  Whether the pypi requirement should be editable
+
+## Config Options
+- <a id="arg---tls-no-verify" href="#arg---tls-no-verify">`--tls-no-verify`</a>
+:  Do not verify the TLS certificate of the server
+- <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---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---concurrent-solves" href="#arg---concurrent-solves">`--concurrent-solves <CONCURRENT_SOLVES>`</a>
+:  Max concurrent solves, default is the number of CPUs
+- <a id="arg---concurrent-downloads" href="#arg---concurrent-downloads">`--concurrent-downloads <CONCURRENT_DOWNLOADS>`</a>
+:  Max concurrent network requests, default is `50`
+
+## Git Options
+- <a id="arg---git" href="#arg---git">`--git (-g) <GIT>`</a>
+:  The git url to use when adding a git dependency
+- <a id="arg---branch" href="#arg---branch">`--branch <BRANCH>`</a>
+:  The git branch
+- <a id="arg---tag" href="#arg---tag">`--tag <TAG>`</a>
+:  The git tag
 - <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>

docs/reference/cli/pixi/auth/login.md

@@ -17,19 +17,19 @@ pixi auth login [OPTIONS] <HOST>
 <br>**required**: `true`
 
 ## Options
-- <a id="arg---conda-token" href="#arg---conda-token">`--conda-token <CONDA_TOKEN>`</a>
-:  The token to use on anaconda.org / quetz authentication
+- <a id="arg---token" href="#arg---token">`--token <TOKEN>`</a>
+:  The token to use (for authentication with prefix.dev)
+- <a id="arg---username" href="#arg---username">`--username <USERNAME>`</a>
+:  The username to use (for basic HTTP authentication)
 - <a id="arg---password" href="#arg---password">`--password <PASSWORD>`</a>
 :  The password to use (for basic HTTP authentication)
+- <a id="arg---conda-token" href="#arg---conda-token">`--conda-token <CONDA_TOKEN>`</a>
+:  The token to use on anaconda.org / quetz authentication
 - <a id="arg---s3-access-key-id" href="#arg---s3-access-key-id">`--s3-access-key-id <S3_ACCESS_KEY_ID>`</a>
 :  The S3 access key ID
 - <a id="arg---s3-secret-access-key" href="#arg---s3-secret-access-key">`--s3-secret-access-key <S3_SECRET_ACCESS_KEY>`</a>
 :  The S3 secret access key
 - <a id="arg---s3-session-token" href="#arg---s3-session-token">`--s3-session-token <S3_SESSION_TOKEN>`</a>
 :  The S3 session token
-- <a id="arg---token" href="#arg---token">`--token <TOKEN>`</a>
-:  The token to use (for authentication with prefix.dev)
-- <a id="arg---username" href="#arg---username">`--username <USERNAME>`</a>
-:  The username to use (for basic HTTP authentication)
 
 --8<-- "docs/reference/cli/pixi/auth/login_extender.md:example"

docs/reference/cli/pixi/build.md

@@ -12,25 +12,27 @@ pixi build [OPTIONS]
 ```
 
 ## 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---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---no-incremental" href="#arg---no-incremental">`--no-incremental (-n)`</a>
-:  Whether to build incrementally if possible
+- <a id="arg---target-platform" href="#arg---target-platform">`--target-platform (-t) <TARGET_PLATFORM>`</a>
+:  The target platform to build for (defaults to the current platform)
+<br>**default**: `current_platform`
 - <a id="arg---output-dir" href="#arg---output-dir">`--output-dir (-o) <OUTPUT_DIR>`</a>
 :  The output directory to place the build artifacts
 <br>**default**: `.`
+- <a id="arg---no-incremental" href="#arg---no-incremental">`--no-incremental (-n)`</a>
+:  Whether to build incrementally if possible
+
+## Config Options
+- <a id="arg---tls-no-verify" href="#arg---tls-no-verify">`--tls-no-verify`</a>
+:  Do not verify the TLS certificate of the server
+- <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---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---target-platform" href="#arg---target-platform">`--target-platform (-t) <TARGET_PLATFORM>`</a>
-:  The target platform to build for (defaults to the current platform)
-<br>**default**: `current_platform`
-- <a id="arg---tls-no-verify" href="#arg---tls-no-verify">`--tls-no-verify`</a>
-:  Do not verify the TLS certificate of the server
+- <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---concurrent-downloads" href="#arg---concurrent-downloads">`--concurrent-downloads <CONCURRENT_DOWNLOADS>`</a>
+:  Max concurrent network requests, default is `50`
 
 ## Global Options
 - <a id="arg---manifest-path" href="#arg---manifest-path">`--manifest-path <MANIFEST_PATH>`</a>

docs/reference/cli/pixi/clean.md

@@ -18,10 +18,10 @@ pixi clean [OPTIONS] [COMMAND]
 
 
 ## Options
-- <a id="arg---activation-cache" href="#arg---activation-cache">`--activation-cache`</a>
-:  Only remove the activation cache
 - <a id="arg---environment" href="#arg---environment">`--environment (-e) <ENVIRONMENT>`</a>
 :  The environment directory to remove
+- <a id="arg---activation-cache" href="#arg---activation-cache">`--activation-cache`</a>
+:  Only remove the activation cache
 
 ## Global Options
 - <a id="arg---manifest-path" href="#arg---manifest-path">`--manifest-path <MANIFEST_PATH>`</a>

docs/reference/cli/pixi/clean/cache.md

@@ -12,14 +12,14 @@ pixi clean cache [OPTIONS]
 ```
 
 ## Options
+- <a id="arg---pypi" href="#arg---pypi">`--pypi`</a>
+:  Clean only the pypi related cache
 - <a id="arg---conda" href="#arg---conda">`--conda`</a>
 :  Clean only the conda related cache
-- <a id="arg---exec" href="#arg---exec">`--exec`</a>
-:  Clean only `exec` cache
 - <a id="arg---mapping" href="#arg---mapping">`--mapping`</a>
 :  Clean only the mapping cache
-- <a id="arg---pypi" href="#arg---pypi">`--pypi`</a>
-:  Clean only the pypi related cache
+- <a id="arg---exec" href="#arg---exec">`--exec`</a>
+:  Clean only `exec` cache
 - <a id="arg---repodata" href="#arg---repodata">`--repodata`</a>
 :  Clean only the repodata cache
 - <a id="arg---tool" href="#arg---tool">`--tool`</a>

docs/reference/cli/pixi/config/append.md

@@ -19,11 +19,11 @@ pixi config append [OPTIONS] <KEY> <VALUE>
 :  Configuration value to (pre|ap)pend
 <br>**required**: `true`
 
-## Options
-- <a id="arg---global" href="#arg---global">`--global (-g)`</a>
-:  Operation on global configuration
+## Config Options
 - <a id="arg---local" href="#arg---local">`--local (-l)`</a>
 :  Operation on project-local configuration
+- <a id="arg---global" href="#arg---global">`--global (-g)`</a>
+:  Operation on global configuration
 - <a id="arg---system" href="#arg---system">`--system (-s)`</a>
 :  Operation on system configuration
 

docs/reference/cli/pixi/config/edit.md

@@ -16,11 +16,11 @@ pixi config edit [OPTIONS] [EDITOR]
 :  The editor to use, defaults to `EDITOR` environment variable or `nano` on Unix and `notepad` on Windows
 <br>**env**: `EDITOR`
 
-## Options
-- <a id="arg---global" href="#arg---global">`--global (-g)`</a>
-:  Operation on global configuration
+## Config Options
 - <a id="arg---local" href="#arg---local">`--local (-l)`</a>
 :  Operation on project-local configuration
+- <a id="arg---global" href="#arg---global">`--global (-g)`</a>
+:  Operation on global configuration
 - <a id="arg---system" href="#arg---system">`--system (-s)`</a>
 :  Operation on system configuration
 

docs/reference/cli/pixi/config/list.md

@@ -16,12 +16,14 @@ pixi config list [OPTIONS] [KEY]
 :  Configuration key to show (all if not provided)
 
 ## Options
-- <a id="arg---global" href="#arg---global">`--global (-g)`</a>
-:  Operation on global configuration
 - <a id="arg---json" href="#arg---json">`--json`</a>
 :  Output in JSON format
+
+## Config Options
 - <a id="arg---local" href="#arg---local">`--local (-l)`</a>
 :  Operation on project-local configuration
+- <a id="arg---global" href="#arg---global">`--global (-g)`</a>
+:  Operation on global configuration
 - <a id="arg---system" href="#arg---system">`--system (-s)`</a>
 :  Operation on system configuration
 

docs/reference/cli/pixi/config/prepend.md

@@ -19,11 +19,11 @@ pixi config prepend [OPTIONS] <KEY> <VALUE>
 :  Configuration value to (pre|ap)pend
 <br>**required**: `true`
 
-## Options
-- <a id="arg---global" href="#arg---global">`--global (-g)`</a>
-:  Operation on global configuration
+## Config Options
 - <a id="arg---local" href="#arg---local">`--local (-l)`</a>
 :  Operation on project-local configuration
+- <a id="arg---global" href="#arg---global">`--global (-g)`</a>
+:  Operation on global configuration
 - <a id="arg---system" href="#arg---system">`--system (-s)`</a>
 :  Operation on system configuration
 

docs/reference/cli/pixi/config/set.md

@@ -18,11 +18,11 @@ pixi config set [OPTIONS] <KEY> [VALUE]
 - <a id="arg-<VALUE>" href="#arg-<VALUE>">`<VALUE>`</a>
 :  Configuration value to set (key will be unset if value not provided)
 
-## Options
-- <a id="arg---global" href="#arg---global">`--global (-g)`</a>
-:  Operation on global configuration
+## Config Options
 - <a id="arg---local" href="#arg---local">`--local (-l)`</a>
 :  Operation on project-local configuration
+- <a id="arg---global" href="#arg---global">`--global (-g)`</a>
+:  Operation on global configuration
 - <a id="arg---system" href="#arg---system">`--system (-s)`</a>
 :  Operation on system configuration
 

docs/reference/cli/pixi/config/unset.md

@@ -16,11 +16,11 @@ pixi config unset [OPTIONS] <KEY>
 :  Configuration key to unset
 <br>**required**: `true`
 
-## Options
-- <a id="arg---global" href="#arg---global">`--global (-g)`</a>
-:  Operation on global configuration
+## Config Options
 - <a id="arg---local" href="#arg---local">`--local (-l)`</a>
 :  Operation on project-local configuration
+- <a id="arg---global" href="#arg---global">`--global (-g)`</a>
+:  Operation on global configuration
 - <a id="arg---system" href="#arg---system">`--system (-s)`</a>
 :  Operation on system configuration
 

docs/reference/cli/pixi/exec.md

@@ -16,28 +16,30 @@ pixi exec [OPTIONS] [COMMAND]...
 :  The executable to run, followed by any arguments
 
 ## 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---spec" href="#arg---spec">`--spec (-s) <SPECS>`</a>
+:  Matchspecs of packages to install. If this is not provided, the package is guessed from the command
 - <a id="arg---channel" href="#arg---channel">`--channel (-c) <CHANNEL>`</a>
 :  The channels to consider as a name or a url. Multiple channels can be specified by using this field multiple times
-- <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---platform" href="#arg---platform">`--platform (-p) <PLATFORM>`</a>
+:  The platform to create the environment for
+<br>**default**: `current_platform`
 - <a id="arg---force-reinstall" href="#arg---force-reinstall">`--force-reinstall`</a>
 :  If specified a new environment is always created even if one already exists
 - <a id="arg---list" href="#arg---list">`--list <LIST>`</a>
 :  Before executing the command, list packages in the environment Specify `--list=some_regex` to filter the shown packages
-- <a id="arg---platform" href="#arg---platform">`--platform (-p) <PLATFORM>`</a>
-:  The platform to create the environment for
-<br>**default**: `current_platform`
+
+## Config Options
+- <a id="arg---tls-no-verify" href="#arg---tls-no-verify">`--tls-no-verify`</a>
+:  Do not verify the TLS certificate of the server
+- <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---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---spec" href="#arg---spec">`--spec (-s) <SPECS>`</a>
-:  Matchspecs of packages to install. If this is not provided, the package is guessed from the command
-- <a id="arg---tls-no-verify" href="#arg---tls-no-verify">`--tls-no-verify`</a>
-:  Do not verify the TLS certificate of the server
+- <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---concurrent-downloads" href="#arg---concurrent-downloads">`--concurrent-downloads <CONCURRENT_DOWNLOADS>`</a>
+:  Max concurrent network requests, default is `50`
 
 ## Description
 Run a command and install it in a temporary environment.