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 the
  20 project repository, releng repository and opnfvdocs repository.
  21
  22 In your project repo:
  23
  24 #. Add the following files:
  25
  26    *docs/conf.py*
  27
  28    .. literalinclude:: files/conf.py
  29
  30    *docs/conf.yaml*
  31
  32    .. literalinclude:: files/conf.yaml
  33
  34    *docs/requirements.txt*
  35
  36    .. literalinclude:: files/requirements.txt
  37
  38    *tox.ini*
  39
  40    .. literalinclude:: files/tox.ini
  41
  42    *.gitignore*
  43
  44    .tox/
  45    docs/_build/*
  46
  47    *docs/index.rst*
  48
  49    if it doesn't exist along with other index file for directories
  50    (release, development)
  51
  52 In the releng repository:
  53
  54 #. Follow the steps in `this guide`_ from the Linux Foundation Releng team on
  55    bootstrapping a new ReadTheDocs (RTD) project.
  56
  57    This will ensure RTD will update each time docs patches are merged to
  58    the repository.
  59
  60 .. note: In step 4 of the guide, the file this job should be added to is:
  61          **jjb/project/project-jobs.yaml**, where project is the OPNFV project.
  62
  63 .. _`this guide`: https://docs.releng.linuxfoundation.org/en/latest/project-documentation.html#bootstrap-a-new-project
  64
  65
  66 In the opnfvdocs repository:
  67
  68 #. Add a intersphinx link to the opnfvdocs repo:
  69
  70    Here 'example' should be replaced with the name of your project.
  71
  72    .. code-block:: python
  73        :name: docs/conf.py
  74
  75        intersphinx_mapping['example'] = ('http://opnfv-example.readthedocs.io', None)
  76
  77 #. Ensure all references in opnfvdocs are using `:ref:` and not
  78    directly specifying submodule files (No `:doc:` or 'submodules/...'
  79    in `.. toctree:`)
  80
  81 #. Remove the submodule from opnfvdocs::
  82
  83     diff --git a/.gitmodules b/.gitmodules
  84     index 846ab245..aab01642 100644
  85     --- a/.gitmodules
  86     +++ b/.gitmodules
  87     @@ -151,4 +150,0 @@
  88     -[submodule "docs/submodules/releng"]
  89     -       path = docs/submodules/releng
  90     -       url = ../releng
  91     -       branch = master