Thomas Kulik

Together with the 'doc' repository the documentation team provides basic 'tox', 'sphinx' and ReadTheDocs example configuration files to be used by other ONAP projects (except 'doc'). Every project containing documentation in ReStructuredText format needs them. The files are:

• conf.py
• requirements-docs.txt
• tox.ini
• .readthedocs.yaml
• ribbon.css

Always check that the configuration files used in your repository are in sync with the provided examples. The example configs of course can be extended to fulfill specific needs of other ONAP projects. Please note README.md for the details.

EXAMPLES ONLY: 'examples' directory in the 'doc' repository (master):

FULL: Full file and folder structure of the 'doc' repository (master) to show where active config files are generally stored in a repository.

The content of active configuration files in the 'doc' repository may differ from the content of config files for other ONAP projects!

Ensure correct 'defaultbranch' in '.gitreview'

RELEASE: main

BRANCH: 'master'

FILE: doc/.gitreview

DESCR: Check that the 'defaultbranch' entry is pointing to 'master' ('defaultbranch=master'). This can help to avoid that changes are accidentally committed or even published to a wrong branch.

EXAMPLE: active '.gitreview' for 'master' branch, 'doc' project

Update Sphinx configuration file 'conf.py'

RELEASE: main + maintenance (opt)

BRANCH: 'master'

FILE: doc/docs/conf.py

DESCR: The Sphinx build configuration file 'conf.py' contains configuration needed to customize Sphinx input and output behavior. Please follow the instructions below.

1. Set 'release' and 'version' to 'master'
2. Set 'branch' to 'latest'.
3. Set 'intersphinx_mapping' for projects/repositories participating to the release.
4. Remove 'intersphinx_mapping' for projects/repositories not participating to the release.

Also compare the version used in your repository with the example provided in the 'doc' repo and update if required. Be careful if your active configuration file was already extended.

EXAMPLE #1: example 'conf.py' for 'master' branch

EXAMPLE #2: active 'conf.py' for 'master' branch

OPEN: Add reliable source for the info if a project has/hasn't branched.

OPEN: Include changes/actions required because we have introduced constraints-files.

OPEN: Update to 'conf.yaml' required after branching the repo?

OPEN: Add note to keep files/content  in sync: conf.py / list of project specific release notes / references in 'ONAP Components and Functionalities' section

Update Sphinx configuration file 'requirements-docs.txt'

RELEASE: main

BRANCH: 'master'

FILE: doc/docs/etc/requirements-docs.txt

DESCR: The file contains the required libraries to be used by Sphinx. Compare the version used in your repository with the example provided in the 'doc' repo and update if required. Be careful if your active configuration file was already extended.

EXAMPLE #1: example 'requirements-docs.txt' for 'master' branch

EXAMPLE #2: active 'requirements-docs.txt' for 'master' branch

Update Tox configuration file 'tox.ini'

RELEASE: main

BRANCH: 'master'

FILE: doc/tox.ini

DESCR: The file is required to customize different tox environments. Compare the version used in your repository with the example provided in the 'doc' repo and update if required.  Be careful if your active configuration file was already extended.

1. Set correct branch (master) for all lines containing:

-chttps://git.onap.org/doc/plain/etc/upper-constraints.onap.txt?h=master

EXAMPLE #1: example 'tox.ini' for 'master' branch

EXAMPLE #2: active 'tox.ini' for 'master' branch

OPEN: Update 'upper-constraints' entries here after the final version of the file is available in the 'doc' repo

Update ReadTheDocs build configuration file '.readthedocs.yaml'

RELEASE: main + maintenance (opt)

BRANCH: 'master'

FILE: doc/.readthedocs.yaml

DESCR: The ReadTheDocs build configuration file '.readthedocs.yaml' contains configuration needed to customize ReadTheDocs input and output behavior. Please follow the instructions below.

1. Compare the version of the file currently used in your repository with the (basic) version provided in the examples
2. If required, change the file in your repository

Also compare the version used in your repository with the example provided in the 'doc' repo and update if required.  Be careful if your active configuration file was already extended. 

EXAMPLE #1: example '.readthedocs.yaml', same for 'master' branch and '{release}'

EXAMPLE #2: active '.readthedocs.yaml', same for 'master' branch and '{release}'

Update ReadTheDocs configuration file 'ribbon.css'

RELEASE: main + maintenance (opt)

BRANCH: 'master'

FILE: doc/docs/_static/css/ribbon.css

DESCR: The ReadTheDocs configuration file 'ribbon.css' has - among others - an effect on the width of a RTD documentation page. The width has been limited to ensure good readability. Please follow the instructions below.

1. Compare the version of the file currently used in your repository with the (basic) version provided in the examples
2. If required, change the file in your repository

Also compare the version used in your repository with the example provided in the 'doc' repo and update if required. Be careful if your active configuration file was already extended. 

EXAMPLE #1: example 'ribbon.css', same for 'master' branch and '{release}'

EXAMPLE #2: active 'ribbon.css', same for 'master' branch and '{release}'

Update 'doc' project release notes incl. Jira link

RELEASE: main + maintenance (opt)

BRANCH: 'master'

FILE: doc/docs/release-notes.rst

DESCR: The file contains a description of the latest changes in the 'doc' project itself. Update it accordingly for the new release. Also update the Jira link to the '{release}' issues at the bottom of the file.

EXAMPLE: 'release-notes.rst' for 'master' branch

› View in RTD

OPEN: Evaluate if we can/should have only 'placeholder' files in the 'master' branch. This may avoid confusion in case people are looking to 'master' and seeing release specific content (e.g. related to 'istanbul'). Or should we remove - at least - release names in the RTD navigation (column on the left)?

Update composite release notes

RELEASE: main + maintenance (opt)

BRANCH: 'master'

FILE: doc/docs/release/index.rst

DESCR: This file contains a brief overview about the advantages and latest developments related to the new release. It is also known as the 'composite' release note. The text is authored by the 'doc' team together with the ONAP TSC chair. We are using information from the 'Release Key Updates' table which is maintained by the projects during the release process (e.g. 'Release Key Updates' for the 'istanbul' release). The content is provided in text form and has to be converted to reStructuredText format manually.

Additional sources of information:

• Jira: Set a filter to select all Jira tickets which were assigned to the release (e.g. Jira tickets for the 'Istanbul' maintenance release #1) to see what has changed. Update the file accordingly - especially the release date.
• Gerrit: Choose the OOM project in Gerrit and switch to the log messages for the required ONAP release (e.g. changes in OOM for the 'Istanbul' release). Then check what has caused changes to OOM since the date the previous version of ONAP was released.

CONTACT: Sandra Jackson (Deactivated) Paweł Pawlak 

EXAMPLE: 'index.rst' for 'master' branch

› View in RTD

OPEN: Add a task/milestone to the release process?

OPEN: Describe the process of conversion to reStructuredText format. Example Source

Update list of project specific release notes

RELEASE: main + maintenance (opt)

BRANCH: 'master'

FILE: doc/docs/release/component-release-notes.rst

DESCR: This file contains a table of contents (TOC) for project specific release notes. Important to know: Beginning with the 'jakarta' release a project/repository contributing to the documentation of the release needs to a) be actively maintained and b) create a branch for the new release. Otherwise the project/repository will not be included. Update the file accordingly for the new release.

EXAMPLE: 'component-release-notes' for 'master' branch

› View in RTD

OPEN: Add reliable source for 'release participating projects/repositories' and their 'maintenance-state'.

OPEN: Describe how to locate and check all the project specific release notes (updated? release number/release name correct? ...).

OPEN: Evaluate if we can/should have only 'placeholder' files in the 'master' branch. This may avoid confusion in case people are looking to 'master' and seeing release specific content (e.g. related to 'istanbul'). Or should we remove - at least - release names in the RTD navigation (column on the left)?

Update release history

RELEASE: main + maintenance

BRANCH: 'master'

FILE: doc/docs/release/history.rst

DESCR: This file contains a table with the release history (release number, date, name). Update the file accordingly for the new release.

EXAMPLE: 'history.rst' for 'master' branch

› View in RTD

OPEN: Additional check and update by Architecture Subcommittee required?

Update 'ONAP Overview'

RELEASE: main + maintenance (opt)

BRANCH: 'master'

FILE: docs/platform/overview/index.rst

DESCR: This file contains an overview of ONAP authored together with the architecture subcommittee. Update the file accordingly for the new release.

CONTACT: Byung-Woo Jun 

EXAMPLE: 'overview.rst' for 'master' branch

› View in RTD

OPEN: Activity for the Architecture Subcommittee (change rst file and propose a patch)? Add task/milestone to the release process? To be aligned with marketing department?

Update architecture description

RELEASE: main + maintenance (opt)

BRANCH: 'master'

FILE: doc/docs/platform/architecture/index.rst

DESCR: This file contains a description of the ONAP architecture authored together with the architecture subcommittee. Update the file accordingly for the new release.

CONTACT:Byung-Woo Jun 

EXAMPLE: 'docs/platform/architecture/index.rst' for 'master' branch

› View in RTD

OPEN: Activity for the Architecture Subcommittee (change rst file and propose a patch)? Add task/milestone to the release process? To be aligned with marketing department?

Update interactive ONAP architecture overview diagram and related files

RELEASE: main + maintenance (opt)

BRANCH: 'master'

FILE #1: doc/docs/platform/architecture/media/onap-architecture-overview-interactive.svg

FILE #2: doc/docs/platform/architecture/media/onap-architecture-overview-notes.txt

FILE #3: doc/docs/platform/architecture/index.rst

FILE #4: doc/docs/platform/architecture/media/onap-architecture-overview-labels-and-links.xlsx

CONTACT: Byung-Woo Jun  Thomas Kulik

DESCR: Please follow the instructions below.

1. Optional: Open the file 'onap-architecture-overview-labels-and-links.xlsx', check if links are reachable. Update file if required. (to be detailed)
2. The interactive ONAP architecture overview (svg format, maintained by the 'doc' project team) needs to be aligned with the official ONAP architecture diagram maintained by the Architecture Subcommittee (e.g. Istanbul-R9 Architecture Diagram). Open the file 'onap-architecture-overview-interactive.svg' in Inkscape and change the architecture building blocks accordingly. Read more about this in the onap-architecture-overview-notes.txt .
3. In the 'Objects' window find the 'releaseinfo.link' object. Make it visible by clicking on the 'closed eye' symbol to change it to an 'open eye' symbol. Now the release info should be visible on the overview.
4. Click on tab 'Object attributes' and check/update the content of the field 'Href:' (the link must point to 'latest').
5. Update the content of the field 'Title:' to show the new release number and name (e.g. 'ONAP Release 9 »Istanbul«').
6. In the 'Objects' window find the 'releaseinfo.link' object. Make it invisible again by clicking on the 'open eye' symbol to change it to a 'closed eye' symbol. Now the release info should be no longer visible on the overview.
7. Save the file.
8. Save the file a second time, but with a new filename. Use 'onap-architecture-overview-interactive-path.svg'.
9. Then select all elements in the map and use the Inkscape function 'Path → Object to Path' to convert all elements to pathes. Save the overview map, close Inkscape (and remember to do no  further changes to this 'pathed' version of the overview).
10. Info: In 'doc/docs/guides/onap-developer/architecture/onap-architecture.rst' you find a '.. raw:: html' section which contains the filename of the interactive ONAP architecture overview. You must use the filename of the 'pathed' version ('onap-architecture-overview-interactive-path.svg') here!

EXAMPLE: 'doc/docs/platform/architecture/index.rst' for 'master' branch

› View in RTD

OPEN: Describe how to update and test links in xls and svg.

Update references in 'ONAP Components and Functionalities' section

RELEASE: main + maintenance (opt)

BRANCH: 'master'

FILE: docs/platform/components/index.rst

DESCR: This file contains references to the detailed documentation of ONAP projects, components and functionalities. Important to know: Beginning with the 'jakarta' release a project/repository contributing to the documentation of the release needs to a) be actively maintained and b) create a branch for the new release. Otherwise the project/repository will not be included. Update the file accordingly for the new release.

EXAMPLE: 'docs/platform/components/index.rst' for 'master' branch

› View in RTD

Create new branch of the 'doc' repository using gerrit

RELEASE: main

BRANCH: source/initial='master', target/new={release}

FILE: n/a

DESCR: Please follow the instructions below.

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

Note: You are not allowed to delete a branch. If you need to (maybe due to a typo in the process of creation) you have to raise a ticket at the LF IT Support.

IMPORTANT: To trigger the documentation build in ReadTheDocs, you must change at least one of the ReStructuredText files (.rst) in the new branch. Only branching the repository does not trigger the RTD doc build process. Consequently the '{release}' version of documentation is missing in RTD.

OPEN: Currently we are branching the repository early - and consequently have to cherry-pick the changes (done in 'master') for '{release}'. Check if it is ok to branch late (after changing the majority of files). So we can reduce cherry-pick efforts.

Set correct 'defaultbranch' in '.gitreview'

RELEASE: main

BRANCH: {release}

FILE: doc/.gitreview

DESCR: Add/update the 'defaultbranch' entry accordingly (e.g. 'defaultbranch=istanbul' for the 'istanbul' branch/release). This can help to avoid that changes are accidentally committed or even published to a wrong branch.

EXAMPLE: active '.gitreview' for 'jakarta' branch

Update Sphinx build configuration file 'conf.py'

RELEASE: main + maintenance (opt)

BRANCH: {release}

FILE: doc/docs/conf.py

DESCR: The Sphinx build configuration file 'conf.py' contains configuration needed to customize Sphinx input and output behavior. Please follow the instructions below.

1. Set 'release' and 'version' to '{release}'.
2. Set 'branch' to '{release}'.
3. Set 'intersphinx_mapping' for all participating projects/repositories.

Note: Beginning with the 'jakarta' release a project/repository contributing to the documentation of the release needs to a) be actively maintained and b) create a branch for the new release. Otherwise the project/repository will not be included. Intersphinx mapping sections for those projects/repositories are removed from 'conf.py'.

EXAMPLE: active 'conf.py' for 'jakarta' branch

OPEN: Add reliable source for the info if a project has/hasn't branched.

OPEN: Include changes/actions required because we have introduced constraints-files.

OPEN: Update to 'conf.yaml' required after branching the repo?

Update Tox configuration file 'tox.ini'

RELEASE: main

BRANCH: {release}

FILE: doc/tox.ini

DESCR: The file is required to customize different tox environments. Compare the version used in your repository with the example provided in the 'doc' repo and update if required.  Be careful if your active configuration file was already extended.

1. Set correct branch {release} for all lines containing:

-chttps://git.onap.org/doc/plain/etc/upper-constraints.onap.txt?h={release}

EXAMPLE #1: example 'tox.ini' for 'master' branch

EXAMPLE #2: active 'tox.ini' for 'master' branch

Update interactive ONAP architecture overview diagram and related files

RELEASE: main + maintenance (opt)

BRANCH: {release}

FILE #1: doc/docs/platform/architecture/media/onap-architecture-overview-interactive.svg

FILE #2: doc/docs/platform/architecture/media/onap-architecture-overview-notes.txt

FILE #3: doc/docs/platform/architecture/index.rst

FILE #4: docs/platform/architecture/media/onap-architecture-overview-labels-and-links.xlsx

CONTACT: Thomas Kulik

DESCR: Please follow the instructions below.

1. PREREQUISITE: The interactive ONAP architecture overview (svg format, maintained by the 'doc' project team) must already have been aligned to the official ONAP architecture diagram maintained by the Architecture Subcommittee (e.g. Istanbul-R9 Architecture Diagram). See above. If not aligned yet, update the diagram in the 'master' branch and cherry-pick it for '{release}'.
2. Optional: Open the file 'onap-architecture-overview-labels-and-links.xlsx', change links to point to  '{release}' and not 'latest'; check if links are reachable (to be detailed).
3. Open file 'onap-architecture-overview-interactive.svg' in Inkscape
4. In the 'Objects' window find the 'releaseinfo.link' object. Make it visible by clicking on the 'closed eye' symbol to change it to an 'open eye' symbol. Now the release info should be visible on the overview.
5. Click on tab 'Object attributes' and check the content of the field 'Href:' (the link must point to '{release}', not 'latest').
6. Check also the content of the field 'Title:' to show the new release number and name (e.g. 'ONAP Release 9 »Istanbul«').
7. Check and update all embedded links to point to '{release}' and not 'latest'. (to be detailed; e.g. search and replace in an text editor?)
8. Save the file.
9. Save the file a second time, but with a new filename. Use 'onap-architecture-overview-interactive-path.svg'.
10. Then select all  elements in the map and use the Inkscape function 'Path → Object to Path' to convert all elements to pathes. Read more about this in the onap-architecture-overview-notes.txt . Save the overview map, close Inkscape (and remember to do no  further changes to this 'pathed' version of the overview).
11. Info: In 'doc/docs/platform/architecture/index.rst' you find a '.. raw:: html' section which contains the filename of the interactive ONAP architecture overview. You must use the filename of the 'pathed' version ('onap-architecture-overview-interactive-path.svg') here!

EXAMPLE: 'onap-architecture.rst' for 'istanbul' branch (TO BE CHANGED! Needs an update to 'index.rst' if 'Kohn' release is available)

› View in RTD

OPEN: Update example if 'Kohn' release is available ( onap-architecture.rst → doc/docs/platform/architecture/index.rst )

OPEN: Describe how to update and test links in xls and svg.

OPEN: Update links in 'onap-architecture-overview-interactive.svg' by using an editor and replacing very carefully '/en/latest/' with '/en/{release}'? Do all links work?

Deactivate outdated release documentation

RELEASE: older than 'current -1'

BRANCH: n/a

FILE: n/a

DESCR: Generally, the latest release of ONAP and the one before is supported. Older releases of documentation can be deactivated in RTD. Remove them from the list of 'Active Versions' which is available for every project (repository). Keep only 'latest', {current release} and {current release -1}. For unmaintained projects only keep 'latest' in the list of 'Active Versions'. You need to be administered as a 'Maintainer' in RTD for every single project you like to (de)activate versions.

EXAMPLE: n/a

OPEN: To be detailed