Repository Service for TUF ‘s main/umbrella Repository maintains the Guide and the Development Guide.

The documentation in structure is:

├── diagrams
├── source
    ├── _static
    ├── devel
       ├── <component>_design.rst
    ├── guide
       ├── index.rst
       ├── installation
       ├── <component-guide>
    └── index.rst

To gives the component’s developer the responsibility and the flexibility to build their documentation. The component needs to follow a structure.

The Repository Service for TUF main/umbrella uses high-level documentation from the components to build the Guide and the Development Guide.

The components documentation also follows a required structure:

├── diagrams [   ├── <component-name>-C1.puml '[C1 Design level]'   ├── <component-name>-C2.puml '[C2 Design level]'   └── <component-name>-C3.puml '[C3 Design level]'   └── <component-name>-specifics-feature.puml
└── source
    ├── guide '[All `User Guide` information in this folder]'
       └── index.rst
       └── ...
       └── details.rst
    ├── devel
       ├── design.rst '[Only C1-C2 level (high-level) details/information]'
       ├── ...
       └── index.rst
    └── index.rst
  • All diagrams needs to be in docs/diagrams and must to use <component-name> in the name

  • The umbrella repository will merge the source/guide into the main guide.

  • The umbrella repository will use the source/devel/design in the main Development Guide, so add to this document only the high-level information for Developers.

Each component will build your own documentation with more low level and specific information as well.

Building Documentation

The umbrella repository has the component as git sub-module and builds the documentation using the Makefile (make docs)

For each component, the make docs should also be available.

Releasing new Documentation Version

In the umbrella repository > Releases > Draft new release

Choose a new release tag based on the Versioning documentation.

After Click on Generate release notes and keep the relevant updates.