Update Submodule Transition Guide

Adds headers for each section, updates the jobs config needed for
projects, adds an example for updating references in opnfvdocs, and
clarifies a few changes such as where the intersphinx link should go.

Change-Id: I9b1c09bdc5df776e36f0f14bc80d19dd3f8c679e
Signed-off-by: Trevor Bramwell <tbramwell@linuxfoundation.org>

2 files changed, 45 insertions, 22 deletions

diff --git a/docs/how-to-use-docs/files/build.yaml b/docs/how-to-use-docs/files/build.yaml
index 452655ae5..d04ff731b 100644
--- a/docs/how-to-use-docs/files/build.yaml
+++ b/docs/how-to-use-docs/files/build.yaml
@@ -3,11 +3,6 @@
     name: PROJECT
     project-name: '{name}'
 
-    build-timeout: 60
-    build-node: 'opnfv-build'
-    gerrit-server-name: 'gerrit.opnfv.org'
-    jenkins-ssh-credential: 'd42411ac011ad6f3dd2e1fa34eaa5d87f910eb2e'
-
     project-pattern: '{name}'
     rtd-build-url: RTD_BUILD_URL
     rtd-token: RTD_TOKEN
diff --git a/docs/how-to-use-docs/local-build-transition.rst b/docs/how-to-use-docs/local-build-transition.rst
index c22951184..c8d196a67 100644
--- a/docs/how-to-use-docs/local-build-transition.rst
+++ b/docs/how-to-use-docs/local-build-transition.rst
@@ -26,6 +26,9 @@ repositories:
 .. _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:
@@ -59,6 +62,13 @@ In your project repo:
 
    .. 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
@@ -74,29 +84,47 @@ 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 a intersphinx link to the opnfvdocs repo:
+#. Add an intersphinx link to the opnfvdocs repo configuration:
 
-   Here 'example' should be replaced with the name of your project.
+   *docs/conf.py*
 
    .. code-block:: python
-       :name: docs/conf.py
 
-       intersphinx_mapping['example'] = ('http://opnfv-example.readthedocs.io', None)
+      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`_.
 
-#. Ensure all references in opnfvdocs are using `:ref:` and not
-   directly specifying submodule files (No `:doc:` or 'submodules/...'
-   in `.. toctree:`)
+   .. _here: https://docs.releng.linuxfoundation.org/en/latest/project-documentation.html#cross-reference-external-docs
 
-#. Remove the submodule from opnfvdocs::
+#. Remove the submodule from opnfvdocs, replacing *<project>* with your
+   project and commit the change::
 
-    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
+     git rm docs/submodules/<project>
+     git commit -s
+     git review