Documentation directory layout

Cloud-init’s documentation directory structure, with respect to the root directory:

/doc/
    - examples/
    - man/
    - module-docs/
    - rtd/
        - tutorial/
        - howto/
        - explanation/
        - reference/

        - development/
        - static/
            - css/
            - js/
            - *logos*
        - *conf.py*
        - *index.rst*
        - *links.txt*
    - rtd_html/
    - sources/

examples/

man/

This subdirectory contains the Linux man pages for the binaries provided by cloud-init.

module-docs/

The documentation for modules is generated automatically using YAML files and templates. Each module has its own sub-directory, containing:

  • data.yaml file: Contains the text and descriptions rendered on the modules documentation page.

  • example*.yaml files: These examples stand alone as valid cloud-config. They always start with #cloud-config, and ideally, should also have some accompanying discussion or context in the comment field in the data.yaml file to explain what’s happening.

Edit existing module docs

In the data.yaml file, the fields support reStructuredText markup in the description and comment fields. With the pipe character (|) preceding these fields, the text will be preserved so that using rST directives (such as notes or code blocks) will render correctly in the documentation. If you don’t need to use directives, you can use the greater-than character (>), which will fold broken lines together into paragraphs (while respecting empty lines).

Create new module docs

Creating documentation for a new module involves a little more work, and the process for that is outlined in the contributing modules page.

rtd/

This subdirectory is of most interest to anyone who wants to create or update either the content of the documentation, or the styling of it.

  • The content of the documentation is organised according to the Diataxis framework and can be found in the subdirectories: tutorial/, howto/, explanation/, and reference/.

  • The development/ subdirectory contains documentation for contributors.

  • static/ contains content that relates to the styling of the documentation in the form of custom CSS or javascript files found in css/ and js/ respectively. This is also where you can find the cloud-init logo.

  • conf.py contains Sphinx configuration commands.

  • index.rst is the front page of the documentation.

  • links.txt contains common (and reusable) links so that you do not need to define the same URLs on every page and can use a more convenient shorthand when referencing often-used links.

rtd_html/

When the documentation is built locally using tox -e doc, the built pages can be found in this folder.

sources/

This subdirectory contains demos which can help the reader understand how parts of the product work.