Project Documentation Guide

Documentation is an important aspect to any software project. LF-Releng provides some recommended tools for projects to get setup with their own documentation and we will attempt to describe them in this guide.

Tools

The main tools recommended to generate docs is Sphinx and reStructuredText. Sphinx is a tool for generating documentation from a set of reStructuredText documents.

LF provides lfdocs-conf as a convenience package that will pull in the most common documentation dependencies and configuration for your project. global-jjb provides job templates that can build and publish the documentation.

Framework

Typically every project like ONAP, OpenDaylight, OPNFV, etc… have a “documentation” project. This project provides a gateway to all documentation for the project and typically is the index page of any project’s http://docs.PROJECT_DOMAIN url.

Project-specific documentation will configure as subprojects in ReadTheDocs and are available at http://docs.PROJECT_DOMAIN/projects/PROJECT

Linking between projects are possible via intersphinx linking.

Bootstrap a New Project

Bootstrap your project with documentation by following these steps.

  1. Setup lfdocs-conf with the Install Procedures.

  2. Add project to ReadTheDocs following instructions here

    Open a Helpdesk ticket if you require assistence here.

  3. Create RTD Generic Webhook

    Follow the steps described in the rtd-jobs documentation then record the rtd-build-url and rtd-token for the next step.

  4. Add the rtd jobs to your project

    Open up your project.yaml in the ci-management repo and add this section:

    - project:
        name: PROJECT
        jobs:
          - '{project-name}-rtd-jobs'
    
        project-pattern: PROJECT
        rtd-build-url: RTD_BUILD_URL
        rtd-token: RTD_TOKEN
    
    name:Project name in Gerrit converting forward slashes (/) to dashes (-).
    project-pattern:
     Project name as defined in Gerrit.
    rtd-build-url:This is the generic webhook url from readthedocs.org. Refer to the above instructions to generate one. (Check Admin > Integrations > Generic API incoming webhook)
    rtd-token:The unique token for the project Generic webhook. Refer to the above instructions to generate one. (Check Admin > Integrations > Generic API incoming webhook)

    More details on rtd job template configuration and parameters is available here.

    Note

    If lfdocs-conf patches are already merged then issue a ‘remerge’ so the publish job can push the docs to ReadTheDocs.

Add a project to ReadTheDocs

In this task we will add a project to ReadTheDocs. This is necessary to let ReadTheDocs know where to pull your docs to build from.

Warning

Remember to add lf-rtd as a maintainer of the project. This is to ensure that LF staff can continue to manage this project even if the project owner stops working on the project. If you would like helpdesk to assist with creating the project for you then open a helpdesk ticket.

  1. Login to ReadTheDocs (LFIT can use the lf-rtd account)

  2. Click “Import a Project” on the dashboard

  3. Click “Import Manually”

  4. Setup Project

    Import Project page

    Import Project page

    1. Give the project a name

      Note

      Remember this name to setup the Jenkins jobs.

    2. Provide the Anonymous HTTP clone URL eg. https://gerrit.linuxfoundation.org/infra/releng/docs-conf

    3. Repository type: Git

    4. Click Next

  5. Click Admin > Maintainers

  6. Ensure lf-rtd is a maintainer of the project

  7. Setup sub-project

    If this project is not the main documentation project then it needs to be setup as a sub-project of the main documentation project. This will create a subproject link for your project under http://docs.PROJECT_DOMAIN/projects/YOUR_PROJECT

    Note

    Either the main documentation project’s committers or LF Staff will need to perform this step. If documentation project committers are not available contact the Helpdesk to have LF Staff take care of the subproject configuration.

    1. Goto the main documentation project’s ReadTheDocs admin page

    2. Click Sub-projects

    3. Click Add subproject

    4. Select the child project (the one we created above)

    5. Give it an Alias

      Note

      Typically the repo name. Forward slashes are not allowed so convert them to hyphens.