Submodule Transition¶

Moving away from submodules.

At the cost of some release-time overhead, there are several benefits the transition provides projects:

Local builds - Projects will be able to build and view there docs locally, as they would appear on the OPNFV Docs website.
Reduced build time - Patchset verification will only run against individual projects docs, not all projects.
Decoupled build failures - Any error introduced to project’s docs would not break builds for all the other projects

Steps¶

To make the transition the following steps need to be taken across three repositories:

Your project repository (Ex. Fuel)
The Releng repository
The OPNFV Docs repository

Adding a Local Build¶

In your project repo:

Add the following files:

docs/conf.py

from docs_conf.conf import *  # noqa: F401,F403

docs/conf.yaml

---
project_cfg: opnfv
project: Example

docs/requirements.txt

lfdocs-conf
sphinx_opnfv_theme
# Uncomment the following line if your project uses Sphinx to document
# HTTP APIs
# sphinxcontrib-httpdomain

tox.ini

[tox]
minversion = 1.6
envlist =
    docs,
    docs-linkcheck
skipsdist = true

[testenv:docs]
deps = -rdocs/requirements.txt
commands =
    sphinx-build -b html -n -d {envtmpdir}/doctrees ./docs/ {toxinidir}/docs/_build/html
    echo "Generated docs available in {toxinidir}/docs/_build/html"
whitelist_externals = echo

[testenv:docs-linkcheck]
deps = -rdocs/requirements.txt
commands = sphinx-build -b linkcheck -d {envtmpdir}/doctrees ./docs/ {toxinidir}/docs/_build/linkcheck

.gitignore

.tox/ docs/_build/*

docs/index.rst

If this file doesn’t exist, it will need to be created along any other missing index file for directories (release, development). Any example of the file’s content looks like this:

.. This work is licensed under a Creative Commons Attribution 4.0 International License.
.. SPDX-License-Identifier: CC-BY-4.0
.. (c) Open Platform for NFV Project, Inc. and its contributors

.. _<project-name>:

==============
<project-name>
==============

.. toctree::
   :numbered:
   :maxdepth: 2

   release/release-notes/index
   release/installation/index
   release/userguide/index
   scenarios/index

You can verify the build works by running:

tox -e docs

Creating a CI Job¶

In the releng repository:

Update your project’s job file jjb/<project>/<projects-jobs.yaml with the following (taken from this guide):

---
- project:
    name: PROJECT
    project: PROJECT
    project-name: 'PROJECT'

    project-pattern: 'PROJECT'
    rtd-build-url: RTD_BUILD_URL
    rtd-token: RTD_TOKEN

    jobs:
      - '{project-name}-rtd-jobs'

You can either send an email to helpdesk in order to get a copy of RTD_BUILD_URL and RTD_TOKEN, ping aricg or bramwelt in #opnfv-docs on Freenode, or add Aric Gardner or Trevor Bramwell to your patch as a reviewer and they will pass along the token and build URL.

Removing the Submodule¶

In the opnfvdocs repository:

Add an intersphinx link to the opnfvdocs repo configuration:

docs/conf.py
```
intersphinx_mapping['<project>'] = ('http://opnfv-<project>.readthedocs.io', None)
```
If the project exists on ReadTheDocs, and the previous build was merged in and ran, you can verify the linking is working currectly by finding the following line in the output of tox -e docs:
```
loading intersphinx inventory from https://opnfv-<project>.readthedocs.io/en/latest/objects.inv...
```
Ensure all references in opnfvdocs are using :ref: or :doc: and not directly specifying submodule files with ../submodules/<project>.

For example:
```
.. toctree::

   ../submodules/releng/docs/overview.rst
```
Would become:
```
.. toctree::

   :ref:`Releng Overview <releng:overview>`
```
Some more examples can be seen here.
Remove the submodule from opnfvdocs, replacing <project> with your project and commit the change:
```
git rm docs/submodules/<project>
git commit -s
git review
```