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>

3 files changed, 59 insertions, 14 deletions

diff --git a/docs/how-to-use-docs/files/build.yaml b/docs/how-to-use-docs/files/build.yaml
new file mode 100644
index 000000000..452655ae5
--- /dev/null
+++ b/docs/how-to-use-docs/files/build.yaml
@@ -0,0 +1,16 @@
+---
+- project:
+    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
+
+    jobs:
+      - '{project-name}-rtd-jobs'
diff --git a/docs/how-to-use-docs/files/index.rst b/docs/how-to-use-docs/files/index.rst
new file mode 100644
index 000000000..0fa6784ab
--- /dev/null
+++ b/docs/how-to-use-docs/files/index.rst
@@ -0,0 +1,18 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. SPDX-License-Identifier: CC-BY-4.0
+.. (c) Open Platform for NFV Project, Inc. and its contributors
+
+.. _<project-name>:
+
+==============
+<project-name>
+==============
+
+.. toctree::
+   :numbered:
+   :maxdepth: 2
+
+   release/release-notes/index
+   release/installation/index
+   release/userguide/index
+   scenarios/index
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: