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 In your project repo:
  30
  31 #. Add the following files:
  32
  33    *docs/conf.py*
  34
  35    .. literalinclude:: files/conf.py
  36
  37    *docs/conf.yaml*
  38
  39    .. literalinclude:: files/conf.yaml
  40
  41    *docs/requirements.txt*
  42
  43    .. literalinclude:: files/requirements.txt
  44
  45    *tox.ini*
  46
  47    .. literalinclude:: files/tox.ini
  48
  49    *.gitignore*::
  50
  51       .tox/
  52       docs/_build/*
  53
  54    *docs/index.rst*
  55
  56    If this file doesn't exist, it will need to be created along any other
  57    missing index file for directories (release, development). Any
  58    example of the file's content looks like this:
  59
  60    .. literalinclude:: files/index.rst
  61
  62 In the releng repository:
  63
  64 #. Update your project's job file
  65    **jjb/<project>/<projects-jobs.yaml** with the following (taken from `this guide`_):
  66
  67    .. literalinclude:: files/build.yaml
  68
  69 You can either send an email_ to helpdesk in order to get a copy of
  70 **RTD_BUILD_URL** and **RTD_TOKEN**, ping *aricg* or *bramwelt* in
  71 *#opnfv-docs* on Freenode, or add *Aric Gardner* or *Trevor Bramwell* to your
  72 patch as a reviewer and they will pass along the token and build URL.
  73
  74 .. _email: mailto:helpdesk@opnfv.org
  75 .. _`this guide`: https://docs.releng.linuxfoundation.org/en/latest/project-documentation.html#bootstrap-a-new-project
  76
  77 In the opnfvdocs repository:
  78
  79 #. Add a intersphinx link to the opnfvdocs repo:
  80
  81    Here 'example' should be replaced with the name of your project.
  82
  83    .. code-block:: python
  84        :name: docs/conf.py
  85
  86        intersphinx_mapping['example'] = ('http://opnfv-example.readthedocs.io', None)
  87
  88 #. Ensure all references in opnfvdocs are using `:ref:` and not
  89    directly specifying submodule files (No `:doc:` or 'submodules/...'
  90    in `.. toctree:`)
  91
  92 #. Remove the submodule from opnfvdocs::
  93
  94     diff --git a/.gitmodules b/.gitmodules
  95     index 846ab245..aab01642 100644
  96     --- a/.gitmodules
  97     +++ b/.gitmodules
  98     @@ -151,4 +150,0 @@
  99     -[submodule "docs/submodules/releng"]
 100     -       path = docs/submodules/releng
 101     -       url = ../releng
 102     -       branch = master