You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 49 Next »


TITLE

P01: Create documentation for an ONAP main release

SUBJECT

This procedure describes the required tasks for the ONAP doc project itself and supplying ONAP projects to create release-specific documentation for an ONAP main release.

TABLE OF CONTENTS

AUTHOR(S)

Thomas Kulik

TASKS

Note: Not every step within a single task is listed here. For example, a detailed description of a 'git commit' and the following 'git review' process is not explained.

0x. Update 'doc/docs/release-notes.rst' in the 'master' branch

This file contains a description of the latest changes in the 'doc' project. Update it accordingly for the new release.

Example: 'release-notes.rst' in the 'master' release/branch


0x. Update 'doc/docs/release/index.rst' in the 'master' branch

This file contains an (marketing) overview about the advantages of and latest developments in the new release. It is also known as the "composite release note". The text is authored by LFN marketing and the ONAP TSC chair. Update the file accordingly.

Example: 'index.rst' (composite release note) in the 'master' release/branch


0x. Update 'doc/docs/release/releaserepos.rst' in the 'master' branch

This file contains an index for project specific release notes. Update it accordingly for the new release.

Example: 'releaserepos.rst' in the 'master' release/branch


0x. Create a new branch of the 'doc' project in gerrit

  1. Open https://gerrit.onap.org/r/admin/repos/doc,branches
  2. Use [CREATE NEW] function on the top right corner
  3. Set 'Branch name' to the name of the upcoming release (e.g. 'istanbul')
  4. Set 'Initial revision' to 'master'
  5. Use [CREATE] to create the new branch

0x. Clone the new doc branch to your development environment

  1. git clone --branch <newbranch> --recurse-submodules ssh://<username>@gerrit.onap.org:29418/doc

0x. Update 'doc/docs/conf.py' in the new branch

  1. Set "branch = 'newbranch'" on top of the file
  2. Set 'intersphinx_mapping' for all participating projects and their repositories
  3. Update 'linkcheck_ignore' entries if required

Note: The different 'intersphinx_mapping' sections in the 'conf.py' reflect the different state of development in the projects and their repositories. We have to differentiate between:

  • Projects that have created a branch for the upcoming release. That's why the entries are mapping to their documentation in the new created branch (branch = 'newbranch').
  • Projects that have not created a branch for the upcoming release, but for a previous release. That's why the entries are mapping to their documentation in a previous branch (e.g. branch = 'frankfurt' or branch = 'guillin').
  • Projects that have never created a branch. That's why the entries are mapping to their documentation in the 'master' branch of ONAP (branch = 'latest'). The ONAP 'master' branch is called 'latest' in ReadTheDocs.

Example #1: 'conf.py' for the 'master' release/branch

Example #2: 'conf.py' for the 'honolulu' release/branch

 


0x. Update 'doc/.gitreview' in the new branch

  1. Add/update the 'defaultbranch' (e.g. 'defaultbranch=honolulu')

Example: '.gitreview' for the 'honolulu' release/branch

 


0x. Lorem ipsum dolor sit amet

  1. Lorem ipsum dolor sit amet
  • No labels