docs: Add a reference for the CLI

.github/workflows/docs.yml

@@ -30,7 +30,46 @@ concurrency:
   cancel-in-progress: true
 
 jobs:
+  # Generate CLI docs by building the `generate-cli-docs` binary and commiting the result to the PR.
+  generate-cli-docs:
+    if: github.event_name == 'pull_request' && github.repository == 'prefix-dev/rattler-build'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          repository: ${{ github.event.pull_request.head.repo.full_name }}
+          ref: ${{ github.event.pull_request.head.ref }}
+
+      - uses: prefix-dev/[email protected]
+
+      - name: Build docs for PR
+        run: |
+          pixi run generate-cli-docs
+
+      - name: Check for changes
+        id: git_diff
+        run: |
+          git diff --exit-code || echo "has_changes=true" >> $GITHUB_ENV
+
+      - name: Output instructions if there are changes
+        if: env.has_changes == 'true'
+        run: |
+          echo "There are changes in the CLI docs."
+          echo "Please run the following commands to commit and push the changes:"
+          echo ""
+          echo "pixi run commit-cli-docs"
+          echo "git commit -am 'docs: update CLI docs'"
+          echo "git push"
+          echo ""
+          exit 1
+
+      - name: Output message if there are no changes
+        if: env.has_changes != 'true'
+        run: echo "No changes detected."
+
   build-docs:
+    needs: generate-cli-docs
     if: github.ref != 'refs/heads/main' && !startsWith(github.ref, 'refs/tags/v')
     runs-on: ubuntu-latest
     steps:

Cargo.toml

@@ -11,12 +11,14 @@ license = "BSD-3-Clause"
 readme = "README.md"
 description = "A fast CLI tool to build conda packages on Windows, macOS and Linux"
 documentation = "https://prefix-dev.github.io/rattler-build"
+default-run = "rattler-build"
 
 [features]
 default = ['native-tls']
 native-tls = ['reqwest/native-tls', 'rattler/native-tls', 'rattler_installs_packages/native-tls']
 rustls-tls = ['reqwest/rustls-tls', 'reqwest/rustls-tls-native-roots', 'rattler/rustls-tls', 'rattler_installs_packages/rustls-tls']
 tui = ['ratatui', 'crossterm', 'ansi-to-tui', 'throbber-widgets-tui', 'tui-input']
+generate-cli-docs = ["clap-markdown"]
 
 [dependencies]
 serde = { version = "1.0.203", features = ["derive"] }
@@ -115,6 +117,7 @@ reflink-copy = "0.1.17"
 rayon = "1.10.0"
 patch = "0.7.0"
 regex = "1.10.4"
+clap-markdown = { version = "0.1.3", optional = true }
 
 [dev-dependencies]
 insta = { version = "1.39.0", features = ["yaml"] }
@@ -148,6 +151,8 @@ rattler_shell = { git = "https://github.com/mamba-org/rattler", branch = "main"
 rattler_solve = { git = "https://github.com/mamba-org/rattler", branch = "main" }
 rattler_virtual_packages = { git = "https://github.com/mamba-org/rattler", branch = "main" }
 rattler_package_streaming = { git = "https://github.com/mamba-org/rattler", branch = "main" }
+clap-markdown = { git = "https://github.com/ruben-arts/clap-markdown", branch = "main"}
+
 
 # rattler = { path = "../rattler/crates/rattler" }
 # rattler_conda_types = { path = "../rattler/crates/rattler_conda_types" }
@@ -159,3 +164,4 @@ rattler_package_streaming = { git = "https://github.com/mamba-org/rattler", bran
 # rattler_solve = { path = "../rattler/crates/rattler_solve" }
 # rattler_virtual_packages = { path = "../rattler/crates/rattler_virtual_packages" }
 # rattler_package_streaming = { path = "../rattler/crates/rattler_package_streaming" }
+#clap-markdown = { path = "../clap-markdown" }

docs/automatic_linting.md

@@ -1,16 +1,13 @@
-# Automatic linting in VSCode
+# Enabling Automatic Linting in VSCode
 
-The new recipe format comes with a strict JSON scheme. You can find the scheme
-[in this repository](https://github.com/prefix-dev/recipe-format).
+Our new recipe format adheres to a strict JSON schema, which you can access [here](https://github.com/prefix-dev/recipe-format).
 
-It is implemented with `pydantic` and renders to a JSON schema file. The [YAML
-language server extension in
-VSCode](https://marketplace.visualstudio.com/items?itemName=redhat.vscode-yaml)
-can recognize the scheme and give helpful hints during editing.
+This schema is implemented using `pydantic` and can be rendered into a JSON schema file. The [YAML language server extension in VSCode](https://marketplace.visualstudio.com/items?itemName=redhat.vscode-yaml) is capable of recognizing this schema, providing useful hints during the editing process.
 
-With the YAML language server installed, the automatic linting can be enabled by
-adding the following line to the top of the recipe file:
+To enable automatic linting with the YAML language server, you need to add the following line at the beginning of your recipe file:
 
 ```yaml
 # yaml-language-server: $schema=https://raw.githubusercontent.com/prefix-dev/recipe-format/main/schema.json
 ```
+
+**Alternatively**, if you prefer not to add this line to your file, you can install the [JSON Schema Store Catalog extension](https://marketplace.visualstudio.com/items?itemName=remcohaszing.schemastore). This extension will also enable automatic linting for your recipe files.

docs/highlevel.md

@@ -12,29 +12,41 @@ Building of packages consists of several steps. It all begins with a
 `recipe.yaml` file that specifies how the package is to be built and what the
 dependencies are. From the recipe file, `rattler-build` executes several steps:
 
-1. Parse the recipe file and evaluate conditional parts (we will see that later,
-   but parts of the recipe can be conditional, e.g. on Windows vs. macOS)
-2. Retrieve all source files specified in the recipe, such as `.tar.gz` files,
-   `git` repositories or even local paths. Additionally, this step will apply
-   patches that can be specified alongside the source file.
-3. Download and install dependencies into temporary "host" and "build"
-   workspaces. Any dependencies that are needed at build time are installed in
-   this step.
-4. Execute the build script to build/compile the source code and "install" it
-   into the host environment.
-5. Collect _all_ files that are new in the "host" environment (because the build
-   script just created them) and apply some transformations if necessary;
-   specifically, we edit the `rpath` on Linux and macOS to help make binaries
-   relocatable.
-6. Bundle all the files in a package and write out any additional metadata into
-   the `info/index.json`, `info/about.json`, and `info/paths.json` files. This
-   also creates the test files that are bundled with the package.
-7. If any tests are specified in the recipe, then those tests are run. The package
-   is considered "done" if it passes all of the tests, otherwise we move it to a
-   "broken" place.
-
-After this process, a package is created. This package can be uploaded to somewhere
-like a custom [prefix.dev](https://prefix.dev) private or public channel.
+1. **Rendering**:
+
+   Parse the recipe file and evaluate conditionals, Jinja expressions, and
+   variables, and variants.
+
+2. **Fetch source**:
+
+   Retrieve specified source files, such as `.tar.gz` files, `git` repositories, local paths. 
+   Additionally, this step will apply patches that can be specified alongside the source file.
+
+3. **Install build environments**:
+
+   Download and install dependencies into temporary "host" and "build" workspaces.
+   Any dependencies that are needed at build time are installed in this step.
+
+4. **Build source**:
+
+   Execute the build script to _build/compile_ the source code and _install_ it into the host environment.
+
+5. **Prepare package files**:
+
+   Collect _all_ files that are new in the "host" environment and apply some transformations if necessary;
+   specifically, we edit the `rpath` on `Linux` and `macOS` to make binaries relocatable.
+
+6. **Package**:
+
+   Bundle all the files in a package and write out any additional metadata into the `info/index.json`, `info/about.json`, and `info/paths.json` files.
+   This also creates the test files that are bundled with the package.
+
+7. **Test**:
+
+   Run any tests specified in the recipe.
+   The package is considered _done_ if it passes all the tests, otherwise its moved to `broken/` in the output directory.
+
+After this process, a package is created. This package can be uploaded to somewhere like a custom [prefix.dev](https://prefix.dev) private or public channel.
 
 ### How to run `rattler-build`
 
@@ -109,10 +121,10 @@ requirements:
 
 The sections of a recipe are:
 
-| sections       | description                                                                                                                                                     |
-| -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| sections       | description                                                                                                                              |
+|----------------|------------------------------------------------------------------------------------------------------------------------------------------|
 | `context`      | Defines variables that can be used in the Jinja context later in the recipe (e.g. name and version are commonly interpolated in strings) |
-| `package`      | This section defines the name and version of the package you are currently building and will be the name of the final output                                    |
-| `source`       | Defines where the source code is going to be downloaded from and checksums                                                                                 |
-| `build`        | Settings for the build and the build script                                                                                                                 |
-| `requirements` | Allows the definition of build, host, run and run-constrained dependencies                                                                                      |
+| `package`      | This section defines the name and version of the package you are currently building and will be the name of the final output             |
+| `source`       | Defines where the source code is going to be downloaded from and checksums                                                               |
+| `build`        | Settings for the build and the build script                                                                                              |
+| `requirements` | Allows the definition of build, host, run and run-constrained dependencies                                                               |