docs/how-to-use-docs/local-build-transition.rst

   1 Submodule Transition
   2 ====================
   3
   4 Moving away from submodules.
   5
   6 At the cost of some release-time overhead, there are several benefits
   7 the transition provides projects:
   8
   9 * Local builds - Projects will be able to build and view there docs
  10   locally, as they would appear on the OPNFV Docs website.
  11 * Reduced build time - Patchset verification will only run against
  12   individual projects docs, not all projects.
  13 * Decoupled build failures - Any error introduced to project's docs
  14   would not break builds for all the other projects
  15
  16 Steps
  17 -----
  18
  19 To make the transition the following steps need to be taken across three
  20 repositories:
  21
  22 * Your project repository (Ex. Fuel)
  23 * The `Releng`_ repository
  24 * The `OPNFV Docs`_ repository
  25
  26 .. _Releng: https://git.opnfv.org/releng/
  27 .. _`OPNFV Docs`: https://git.opnfv.org/opnfvdocs/
  28
  29 Adding a Local Build
  30 ~~~~~~~~~~~~~~~~~~~~
  31
  32 In your project repo:
  33
  34 #. Add the following files:
  35
  36    *docs/conf.py*
  37
  38    .. literalinclude:: files/conf.py
  39
  40    *docs/conf.yaml*
  41
  42    .. literalinclude:: files/conf.yaml
  43
  44    *docs/requirements.txt*
  45
  46    .. literalinclude:: files/requirements.txt
  47
  48    *tox.ini*
  49
  50    .. literalinclude:: files/tox.ini
  51
  52    *.gitignore*::
  53
  54       .tox/
  55       docs/_build/*
  56
  57    *docs/index.rst*
  58
  59    If this file doesn't exist, it will need to be created along any other
  60    missing index file for directories (release, development). Any
  61    example of the file's content looks like this:
  62
  63    .. literalinclude:: files/index.rst
  64
  65 You can verify the build works by running::
  66
  67   tox -e docs
  68
  69 Creating a CI Job
  70 ~~~~~~~~~~~~~~~~~
  71
  72 In the releng repository:
  73
  74 #. Update your project's job file
  75    **jjb/<project>/<projects-jobs.yaml** with the following (taken from `this guide`_):
  76
  77    .. literalinclude:: files/build.yaml
  78
  79 You can either send an email_ to helpdesk in order to get a copy of
  80 **RTD_BUILD_URL** and **RTD_TOKEN**, ping *aricg* or *bramwelt* in
  81 *#opnfv-docs* on Freenode, or add *Aric Gardner* or *Trevor Bramwell* to your
  82 patch as a reviewer and they will pass along the token and build URL.
  83
  84 .. _email: mailto:helpdesk@opnfv.org
  85 .. _`this guide`: https://docs.releng.linuxfoundation.org/en/latest/project-documentation.html#bootstrap-a-new-project
  86
  87 Removing the Submodule
  88 ~~~~~~~~~~~~~~~~~~~~~~
  89
  90 In the opnfvdocs repository:
  91
  92 #. Add an intersphinx link to the opnfvdocs repo configuration:
  93
  94    *docs/conf.py*
  95
  96    .. code-block:: python
  97
  98       intersphinx_mapping['<project>'] = ('http://opnfv-<project>.readthedocs.io', None)
  99
 100    If the project exists on ReadTheDocs, and the previous build was
 101    merged in and ran, you can verify the linking is working currectly by
 102    finding the following line in the output of **tox -e docs**::
 103
 104      loading intersphinx inventory from https://opnfv-<project>.readthedocs.io/en/latest/objects.inv...
 105
 106 #. Ensure all references in opnfvdocs are using **:ref:** or **:doc:** and
 107    not directly specifying submodule files with *../submodules/<project>*.
 108
 109    For example::
 110
 111      .. toctree::
 112
 113         ../submodules/releng/docs/overview.rst
 114
 115    Would become::
 116
 117      .. toctree::
 118
 119         :ref:`Releng Overview <releng:overview>`
 120
 121    Some more examples can be seen `here`_.
 122
 123    .. _here: https://docs.releng.linuxfoundation.org/en/latest/project-documentation.html#cross-reference-external-docs
 124
 125 #. Remove the submodule from opnfvdocs, replacing *<project>* with your
 126    project and commit the change::
 127
 128      git rm docs/submodules/<project>
 129      git commit -s
 130      git review