summaryrefslogtreecommitdiffstats
path: root/docs/how-to-use-docs/local-build-transition.rst
diff options
context:
space:
mode:
Diffstat (limited to 'docs/how-to-use-docs/local-build-transition.rst')
-rw-r--r--docs/how-to-use-docs/local-build-transition.rst130
1 files changed, 0 insertions, 130 deletions
diff --git a/docs/how-to-use-docs/local-build-transition.rst b/docs/how-to-use-docs/local-build-transition.rst
deleted file mode 100644
index 147cb271c..000000000
--- a/docs/how-to-use-docs/local-build-transition.rst
+++ /dev/null
@@ -1,130 +0,0 @@
-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
-
-.. _Releng: https://git.opnfv.org/releng/
-.. _`OPNFV Docs`: https://git.opnfv.org/opnfvdocs/
-
-Adding a Local Build
-~~~~~~~~~~~~~~~~~~~~
-
-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 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:
-
- .. literalinclude:: files/index.rst
-
-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`_):
-
- .. literalinclude:: files/build.yaml
-
-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.
-
-.. _email: mailto:helpdesk@opnfv.org
-.. _`this guide`: https://docs.releng.linuxfoundation.org/en/latest/project-documentation.html#bootstrap-a-new-project
-
-Removing the Submodule
-~~~~~~~~~~~~~~~~~~~~~~
-
-In the opnfvdocs repository:
-
-#. Add an intersphinx link to the opnfvdocs repo configuration:
-
- *docs/conf.py*
-
- .. code-block:: python
-
- 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`_.
-
- .. _here: https://docs.releng.linuxfoundation.org/en/latest/project-documentation.html#cross-reference-external-docs
-
-#. Remove the submodule from opnfvdocs, replacing *<project>* with your
- project and commit the change::
-
- git rm docs/submodules/<project>
- git commit -s
- git review