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 the project repository, releng repository and opnfvdocs repository. In your project repo: #. Add the following files: *docs/conf.py* .. literalinclude:: files/conf.py *docs/conf.yaml* .. literalinclude:: files/conf.yaml *docs/requirements.txt* .. literalinclude:: files/requirements.txt *tox.ini* .. literalinclude:: files/tox.ini *.gitignore* .tox/ docs/_build/* *docs/index.rst* if it doesn't exist along with other index file for directories (release, development) In the releng repository: #. Follow the steps in `this guide`_ from the Linux Foundation Releng team on bootstrapping a new ReadTheDocs (RTD) project. This will ensure RTD will update each time docs patches are merged to the repository. .. note: In step 4 of the guide, the file this job should be added to is: **jjb/project/project-jobs.yaml**, where project is the OPNFV project. .. _`this guide`: https://docs.releng.linuxfoundation.org/en/latest/project-documentation.html#bootstrap-a-new-project In the opnfvdocs repository: #. Add a intersphinx link to the opnfvdocs repo: Here 'example' should be replaced with the name of your project. .. code-block:: python :name: docs/conf.py intersphinx_mapping['example'] = ('http://opnfv-example.readthedocs.io', None) #. Ensure all references in opnfvdocs are using `:ref:` and not directly specifying submodule files (No `:doc:` or 'submodules/...' in `.. toctree:`) #. Remove the submodule from opnfvdocs:: diff --git a/.gitmodules b/.gitmodules index 846ab245..aab01642 100644 --- a/.gitmodules +++ b/.gitmodules @@ -151,4 +150,0 @@ -[submodule "docs/submodules/releng"] - path = docs/submodules/releng - url = ../releng - branch = master