Update formatting and expand local build guide

These changes will hopefully make it clearer to people working on
transitioning their docs over.

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

1 files changed, 25 insertions, 14 deletions

diff --git a/docs/how-to-use-docs/local-build-transition.rst b/docs/how-to-use-docs/local-build-transition.rst
index 415afe816..c22951184 100644
--- a/docs/how-to-use-docs/local-build-transition.rst
+++ b/docs/how-to-use-docs/local-build-transition.rst
@@ -16,8 +16,15 @@ the transition provides projects:
 Steps
 -----
 
-To make the transition the following steps need to be taken across the
-project repository, releng repository and opnfvdocs repository.
+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/
 
 In your project repo:
 
@@ -39,30 +46,34 @@ In your project repo:
 
    .. literalinclude:: files/tox.ini
 
-   *.gitignore*
+   *.gitignore*::
 
-   .tox/
-   docs/_build/*
+      .tox/
+      docs/_build/*
 
    *docs/index.rst*
 
-   if it doesn't exist along with other index file for directories
-   (release, development)
+   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
 
 In the releng repository:
 
-#. Follow the steps in `this guide`_ from the Linux Foundation Releng team on
-   bootstrapping a new ReadTheDocs (RTD) project.
+#. Update your project's job file
+   **jjb/<project>/<projects-jobs.yaml** with the following (taken from `this guide`):
 
-   This will ensure RTD will update each time docs patches are merged to
-   the repository.
+   .. literalinclude:: files/build.yaml
 
-.. note: In step 4 of the guide, the file this job should be added to is:
-         **jjb/project/project-jobs.yaml**, where project is the OPNFV project.
+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
 
-
 In the opnfvdocs repository:
 
 #. Add a intersphinx link to the opnfvdocs repo: