How to contribute to the Rockcraft documentation¶
Tools and markup¶
The Rockcraft documentation is organised according to the Diátaxis framework. Additionally, some rules are used to ensure that code referred to by the documentation is kept up-to-date and tested thoroughly.
Including code and commands¶
All code-like content going into the documentation must be tested, especially if it is supposed to be reproducible. Pages that include code snippets or terminal commands need to provide this information in separate files that can be included in the project’s test infrastructure.
Categories of the documentation that use code snippets will each have their own
directory with a
code folder within. For example,
will hold code for the tutorials.
Each page that provides technical information to the reader in the form of code
snippets or commands, such as a tutorial or how-to guide, should have its own
folder within the
code directory and contain a
for spread tests.
For example, the
tutorials/hello-world.rst tutorial refers to code
supplied in the
tutorials/code/hello-world/task.yaml file. Additional
YAML files can also be included when needed, as shown here:
tutorials ├─ hello-world.rst └─ code └─ hello-world ├─ task.yaml └─ rockcraft.yaml
These YAML files can also include more than just the snippets that appear in a page. For example, they can include additional commands to set up a test environment or clean up after the test has been run. Each snippet should be delimited with comments that enable them to be conveniently extracted, as in this example:
# [docs:snap-version] snap --version # [docs:snap-version-end]
When including code snippets in a page, use the reStructuredText
literalinclude directive with the
to extract the relevant lines of text. If the indentation of the quoted
code is excessive, use the
dedent option to reduce it to an acceptable
level, as in this example:
.. literalinclude:: code/get-started/task.yaml :language: bash :start-after: [docs:snap-version] :end-before: [docs:snap-version-end] :dedent: 2
Handling code snippets in this systematic way encourages reuse of existing code snippets and helps to ensure that the documentation stays up-to-date.
Build the documentation¶
The How to build the documentation guide contains step-by-step instructions for setting up a virtual environment and building the documentation.
Making a contribution¶
If you have a request or found a problem with the documentation, then please submit an issue. These issues are supervised and regularly triaged by the repository owners. If you don’t receive an answer within 2 weeks, please reply to your own issue asking for an update.
Community contributions are more than welcome. To become an external contributor you should:
create a fork of the Rockcraft repository,
- commit the changes to your fork (ideally to a new branch),
make sure to follow the project’s CONTRIBUTING guidelines,
create a Pull Request against the
Similarly to new issues, new Pull Requests (PR) are also supervised and regularly triaged by the repository owners. If the tests are passing and you don’t receive an answer within 2 weeks, please add a comment to your own PR asking for an update.