Add instructions on adding docs to existing project.

adding_docs_to_existing_code.rst

@@ -0,0 +1,78 @@
+.. _adding_docs_to_the_project:
+
+Adding Sphinx docs to Existing Repositories
+===========================================
+
+So, you need to add some docs for code that we've already written.
+You've come to the right place!
+
+There are two common "setup" scenarios:
+    - :ref:`Project with no Sphinx docs<docs_from_scratch>`
+    - :ref:`Project with existing Sphinx docs, but no docs from code<adding_apidocs>`
+
+No mater where you start, there are some :ref:`common
+enhancements<tweaking_conf_file>` to improve the generated output.
+
+In a nutshell, we use `Sphinx`_ with documentation placed in the
+``docs`` directory off the root of the project.
+
+.. _docs_from_scratch:
+
+Adding Sphinx to a project with no docs yet
+-------------------------------------------
+
+Make sure `Sphinx`_ is installed on your machine (it shouldn't be in
+your project's virtual environment). From the top level project
+directory, run::
+
+    sphinx-apidoc -F -A "RelEng Team" -V "0.1" -o docs $python_module_name
+
+If you happen to have an early stage project, without a python module
+directory yet, GOOD FOR YOU!!! You'll just do the normal
+``sphinx-quickstart``. Please keep the defaults, except for 'autodoc'
+and 'viewcode' (say 'Y'es to both)::
+
+    sphinx-quickstart docs
+
+No matter which way you add Sphinx, don't forget to add ``docs/_build``
+to the project's ``.hgignore`` or ``.gitignore`` file.
+
+.. _adding_apidocs:
+
+Adding autodoc to a project already using Sphinx
+------------------------------------------------
+
+The following command should maintain you existing docs, while adding
+the generated code documentation. From the top directory::
+
+    sphinx-apidoc -o docs $python_module_name
+
+This will produce a file ``modules.rst`` which you'll need to manually
+add into your existing ``index.rst`` file.
+
+.. _tweaking_conf_file:
+
+Tweaking the conf.py file
+-------------------------
+
+After you've added generated documentation to your Sphinx project,
+you'll also need to tweak the generated ``docs/conf.py`` file needs a
+couple of edits to work properly.  Around line 21, add the following
+lines::
+
+    sys.path.insert(0, os.path.abspath('..'))
+    import mock
+    MOCK_MODULES = []
+    for mod_name in MOCK_MODULES:
+        sys.modules[mod_name] = mock.Mock()
+
+The first line ensures the module under development is found. The
+remaining lines are a handy framework for satisfying import requirements
+for your module.
+
+.. note::
+    If you want to import the real code during document generation,
+    you'll need to add it to the read-the-docs requirements file, if it
+    isn't already in your project's requirements.txt file..
+
+.. _Sphinx: http://www.sphinx-doc.org/

index.rst

@@ -30,6 +30,7 @@ Contents:
     :hidden:
 
     adding_repo_to_releng_rtfd_account.rst
+    adding_docs_to_existing_code.rst
     maintaining_these_docs.rst
     releng101/checkin-to-builds.rst
     tobewritten.rst

maintaining_these_docs.rst

@@ -18,4 +18,5 @@ Documenting Source Code
 We use Sphinx to generate our code documentation, and host it on Read the
 Docs. There are two major phases to this:
 
+    - :ref:`adding_docs_to_the_project`
     - :ref:`adding_repo_to_releng_rtfd_account`