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:

$ workshop launch dev
$ workshop run dev docs-run

The workshop is the same one code contributions use; see Launch the 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.

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 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). Documentation branches commonly use a docs/ prefix, for example docs/contributing.

Write

Workshop uses the Canonical documentation starter pack 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 (project-specific conventions and patterns)

• Starter pack

• reST style guide

• reST cheat sheet

The command-line reference pages under docs/reference/cli/ are generated from the source, not edited by hand. See CLI reference 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:

$ workshop run dev docs-check

For the workflows that run the same checks on your pull request, see CI/CD.

Commit

Prefix documentation commits with the Doc: type and an optional scope in square brackets:

Doc[chore]: Align references

Review with the team

Send for review

Submit a pull request, 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. 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, or reach the wider documentation community in the Ubuntu documentation Matrix channel.