# Background Rockcraft is a tool to create rocks – a new generation of secure, stable and OCI-compliant container images, based on Ubuntu. The Rockcraft CLI command reference is currently generated as a multi-page set of documents. It is more user-friendly experience to amalgamate all the commands under one page, `docs/reference/commands.rst`, grouped into the existing sections: * Lifecycle commands * Extension commands * Other commands This issue is part of [Canonical's Open Documentation Academy](https://documentation.academy/). It is a duplicate of canonical/open-documentation-academy#376. # Task Update the command reference generation so that `docs/reference/commands.rst` becomes the single rendered CLI command reference page. These are the recommended steps: 1. Review the current generator in `tools/docs/gen_cli_docs.py`. 2. Change the generation strategy so that command documentation is rendered into `docs/reference/commands.rst` through its included group files, instead of generating separate user-facing pages for each command. 3. Preserve the current three-section structure in `docs/reference/commands.rst`: * Lifecycle commands * Extension commands * Other commands 4. Ensure each section contains the full documentation for the commands in that category. 5. Remove the dependency on the hidden generated per-command table of contents if it is no longer required. Once you’re assigned this issue, please open a pull request directly into [canonical/rockcraft](https://github.com/canonical/rockcraft). In order to contribute, you must sign the [Canonical contributor license agreement](https://canonical.com/legal/contributors). # Prerequisites This issue is a good fit for someone comfortable with: * Python * reStructuredText (`.rst`) * documentation generation scripts Helpful but optional: * familiarity with Sphinx * familiarity with Rockcraft CLI command definitions # What you will learn By working on this issue, you will learn: * Generating CLI documentation from command metadata. * Understanding how `.rst` files are used to compose a rendered documentation page. * Working with the GitHub pull request workflow. # Outcome The final documentation should present all Rockcraft CLI commands on a single rendered reference page: `docs/reference/commands.rst` with the corresponding sections. # Resources * [Rockcraft repository](https://github.com/canonical/rockcraft) * [Command reference page](https://github.com/canonical/rockcraft/blob/main/docs/reference/commands.rst) * [CLI docs generator](https://github.com/canonical/rockcraft/blob/main/tools/docs/gen_cli_docs.py) * [Contributing to the Rockcraft documentation](https://documentation.ubuntu.com/rockcraft/latest/contribute-to-this-documentation/) * [Rockcraft CONTRIBUTING.md](https://github.com/canonical/rockcraft/blob/main/CONTRIBUTING.md) -- helpful for setting up a development environment # Mentor The mentor for this issue is @asanvaq. They are the Technical Author for Rockraft and Chisel. Please feel free to reach out to the mentor on [Matrix](https://matrix.to/#/@sanchovaquera:ubuntu.com) if you have further questions.