# Contribute to this documentation **Workshop**’s documentation lives in the `docs/` directory. A documentation change follows the same arc as a code change, from a local preview through to a merged pull request. ## Set up your work environment All documentation resides in the `docs/` directory. To build and serve it at `127.0.0.1:8000`: ```console $ workshop launch dev $ workshop run dev docs-run ``` The workshop is the same one code contributions use; see [Launch the dev workshop](https://ubuntu.com/workshop/docs//contributing/development.md#contributing-dev-workshop). ### Dependencies The documentation build requires Python 3.11 or later. Documentation dependencies are managed using **uv**: - `docs/requirements.in` contains dependencies specific to **Workshop** documentation. - `docs/requirements.txt` is the final, resolved dependency file. The `.github/workflows/update-sphinx-stack.yaml` workflow generates the final file. For more information about the workflow, see [CI/CD](https://ubuntu.com/workshop/docs//contributing/maintenance.md#contributing-cicd). ## Choose a task Trivial fixes such as spelling, grammar, and punctuation need no planning: open a pull request directly. For a larger change, such as restructuring a section or a bulk edit, open an issue in the [issue tracker](https://github.com/canonical/workshop/issues) first to agree on the approach. ## Draft your work ### Create a branch Name your branch after the change, following the same prefix convention as code contributions (see [Contribute to development](https://ubuntu.com/workshop/docs//contributing/development.md#contributing-development)). Documentation branches commonly use a `docs/` prefix, for example `docs/contributing`. ### Write **Workshop** uses the [Canonical documentation starter pack](https://github.com/canonical/sphinx-stack) together with a custom **Workshop** in-project SDK in `.workshop/` to run and build its documentation; the preferred markup is reStructuredText (reST), with some opinionated style choices evident in the source. See the relevant references before making changes: - [Workshop documentation style guide](https://ubuntu.com/workshop/docs//doc-style-guide.md#doc-style-guide) (project-specific conventions and patterns) - [Starter pack](https://documentation.ubuntu.com/sphinx-stack/latest/) - [reST style guide](https://documentation.ubuntu.com/sphinx-stack/latest/reference/style-guide/) - [reST cheat sheet](https://documentation.ubuntu.com/sphinx-stack/latest/reference/doc-cheat-sheet/) The [command-line reference](https://ubuntu.com/workshop/docs//reference/cli/workshop.md#ref-workshop-cli) pages under `docs/reference/cli/` are generated from the source, not edited by hand. See [CLI reference generation](https://ubuntu.com/workshop/docs//contributing/maintenance.md#contributing-doc-generation) for how they’re produced. ### Test Build the documentation and open the local preview at `127.0.0.1:8000`. Check that your changes render as expected, including tables, admonitions, and cross-references. Run the remaining documentation checks, which cover Markdown style, spelling, inclusive language, and links: ```console $ workshop run dev docs-check ``` For the workflows that run the same checks on your pull request, see [CI/CD](https://ubuntu.com/workshop/docs//contributing/maintenance.md#contributing-cicd). ### Commit Prefix documentation commits with the `Doc:` type and an optional scope in square brackets: ```none Doc[chore]: Align references ``` ## Review with the team ### Send for review Submit a [pull request](https://github.com/canonical/workshop/pulls), limiting it to documentation-related files and prefixing the title with `Doc:`. ### Address quality concerns Your pull request runs the documentation checks: a Sphinx build that fails on warnings, plus style, spelling, and link checks. For the full catalog, see [CI/CD](https://ubuntu.com/workshop/docs//contributing/maintenance.md#contributing-cicd). Address any failures and push follow-up commits until the checks pass. ### Wrap up the review Once the checks pass and a maintainer approves the change, it’s merged and published with the next documentation build. ## Get help and support For documentation questions, open an issue in the [issue tracker](https://github.com/canonical/workshop/issues), or reach the wider documentation community in the [Ubuntu documentation Matrix channel](https://matrix.to/#/#documentation:ubuntu.com).