Add a project documentation guide

Describes the process a project can go through to get their
project setup with ReadTheDocs and Sphinx documentation.

Key topics include "Bootstrap a New Project" and "Add a project
to ReadTheDocs".

Issue: RELENG-762
Change-Id: I4110a1ba39327a83ec70873ca0715747a8f3e84e
Signed-off-by: Thanh Ha <thanh.ha@linuxfoundation.org>

diff --git a/docs/_static/rtd/import_project.png b/docs/_static/rtd/import_project.png
new file mode 100644 (file)
index 0000000..8806340
Binary files /dev/null and b/docs/_static/rtd/import_project.png differ

diff --git a/docs/conf.py b/docs/conf.py
index 62617af..05aed91 100644 (file)
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -19,3 +19,8 @@
 #
 
 from docs_conf.conf import *
+
+linkcheck_ignore = [
+    'http.*PROJECT_DOMAIN.*',
+    'https://gerrit.linuxfoundation.org/infra/releng/docs-conf',
+]

diff --git a/docs/index.rst b/docs/index.rst
index 9b16089..d89429a 100644 (file)
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -15,6 +15,7 @@ Guides:
    best-practices
    gerrit
    jenkins
+   project-documentation
 
 .. TODO Gerrit (RELENG-509)
 .. TODO Jenkins (RELENG-510)

diff --git a/docs/project-documentation.rst b/docs/project-documentation.rst
new file mode 100644 (file)
index 0000000..11b9696
--- /dev/null
+++ b/docs/project-documentation.rst
@@ -0,0 +1,129 @@
+.. _lfdocs-proj-docs:
+
+###########################
+Project Documentation Guide
+###########################
+
+Documentation is an important aspect to any software project. LF-Releng
+provides some recommended tools for projects to get setup with their own
+documentation and we will attempt to describe them in this guide.
+
+Tools
+=====
+
+- :ref:`lfdocs-conf <lfdocs-conf>`
+- :ref:`global-jjb job templates <lfreleng-global-jjb>`
+- `reStructuredText <http://www.sphinx-doc.org/en/stable/rest.html>`_
+- `Sphinx <http://www.sphinx-doc.org>`_
+
+The main tools recommended to generate docs is Sphinx and reStructuredText.
+Sphinx is a tool for generating documentation from a set of reStructuredText
+documents.
+
+LF provides lfdocs-conf as a convenience package that will pull in the most
+common documentation dependencies and configuration for your project.
+global-jjb provides job templates that can build and publish the documentation.
+
+
+Framework
+=========
+
+Typically every project like ONAP, OpenDaylight, OPNFV, etc... have a
+"documentation" project. This project provides a gateway to all documentation
+for the project and typically is the index page of any project's
+http://docs.PROJECT_DOMAIN url.
+
+Project-specific documentation will configure as subprojects in ReadTheDocs and
+are available at http://docs.PROJECT_DOMAIN/projects/PROJECT
+
+Linking between projects are possible via intersphinx linking.
+
+
+Bootstrap a New Project
+=======================
+
+Bootstrap your project with documentation by following these steps.
+
+#. Setup lfdocs-conf with the :ref:`Install Procedures <lfdocs-conf-install>`.
+#. Add project to ReadTheDocs following instructions
+   :ref:`here <lfdocs-create-rtd>`
+
+   Open a :ref:`Helpdesk <lfreleng-docs-helpdesk>` ticket if you require
+   assistence here.
+
+#. Add the rtd jobs to your project
+
+   Open up your project.yaml in the ci-management repo and add this section::
+
+     - project:
+         name: blah
+         jobs:
+           - '{project-name}-rtd-jobs'
+         rtd-project: project
+
+   More details on rtd job template configuration and parameters is available
+   :ref:`here <lf-global-jjb-rtd-jobs>`.
+
+   .. note::
+
+      If lfdocs-conf patches are already merged then issue a 'remerge' so the
+      publish job can push the docs to ReadTheDocs.
+
+
+.. _lfdocs-create-rtd:
+
+Add a project to ReadTheDocs
+============================
+
+In this task we will add a project to ReadTheDocs. This is necessary to let
+ReadTheDocs know where to pull your docs to build from.
+
+.. warning::
+
+   Remember to add lf-rtd as a maintainer of the project. This is to ensure
+   that LF staff can continue to manage this project even if the project owner
+   stops working on the project. If you would like helpdesk to assist with
+   creating the project for you then open a
+   :ref:`helpdesk ticket <lfreleng-docs-helpdesk>`.
+
+#. Login to ReadTheDocs (LFIT can use the lf-rtd account)
+#. Click "Import a Project" on the `dashboard
+   <https://readthedocs.org/dashboard>`_
+#. Click "Import Manually"
+#. Setup Project
+
+   .. figure:: _static/rtd/import_project.png
+      :align: center
+      :alt: Import Project page
+      :scale: 70%
+
+      Import Project page
+
+   a. Give the project a name
+
+      .. note:: Remember this name to setup the Jenkins jobs.
+
+   b. Provide the Anonymous HTTP clone URL
+      eg. https://gerrit.linuxfoundation.org/infra/releng/docs-conf
+   c. Repository type: Git
+   d. Click Next
+
+#. Click Admin > Maintainers
+#. Ensure lf-rtd is a maintainer of the project
+#. Setup sub-project
+
+   .. note::
+
+      If this project is not the main documentation project then it needs to be
+      setup as a sub-project of the main documentation project.
+
+   a. Goto the main documentation project's ReadTheDocs admin page
+   b. Click Sub-projects
+   c. Click Add subproject
+   d. Select the child project (the one we created above)
+   e. Give it an Alias
+
+      .. note::
+
+         Typically the repo name. Forward slashes are not allowed so convert
+         them to hyphens.