Update PTI around documentation jobs

Update our PTI for docs to be more about show Sphinx should operate.
Remove the mention of tox -evenv -- python setup.py build_sphinx which
is super OpenStack specific and ALSO doens't make anything any easier.

Define the Sphinx config and setup and apply it to all of the languages.
Then add a mention of developer-convenience additions for each language.

This should allow us to do sphinx docs one way regardless of language
without adding tox requirements to non-python projects, and to have our
python projects behave in a way consistent with other parts of the
python ecosystem such as readthedocs.

Change-Id: Ief487e1d20ea20facf398367ca03a6385182fb38

reference/project-testing-interface.rst

@@ -31,6 +31,44 @@ project:
 Tools and approaches vary by language, please choose which language is
 relevant to you.
 
+.. _pti-documentation:
+
+Documentation
+-------------
+
+OpenStack has decided to standardize on using Sphinx for project documentation,
+regardless of programming language.
+
+.. note:: The use of sphinx for documentation is intended for documentation
+          that is not written inside of docstrings or code comments.
+          Languages, such as Go, that natively support a system for documenting
+          the code through code comments, should use those native systems.
+          Sphinx is intended to be used for documentation that is not written
+          inline with the code.
+
+To support documentation generation, projects should:
+
+* Have sphinx documentation source in ``doc/source``
+* List python dependencies needed for documentation in ``doc/requirements.txt``
+* List distro package pre-reqs for dependencies in ``bindep.txt`` using the
+  ``doc`` tag.
+* Depend on ``openstackdocstheme`` for documentation and configure it to be
+  used in ``doc/source/conf.py``.
+
+Assuming requirements have been properly installed as indicated by
+``doc/requirements.txt`` and ``bindep.txt``, the following command should
+work with no additional setup and should result in the documentation being
+emitted into ``doc/build``.
+
+.. code-block:: bash
+
+  sphinx-build -b html doc/source doc/build
+
+Language specific instructions supplement these and are in addition to them.
+
+Linux Distributions
+-------------------
+
 The following operating systems are the most popular when deploying OpenStack:
 
 - Ubuntu (`latest LTS`_)

reference/pti/golang.rst

@@ -194,19 +194,24 @@ address or identity, and should map to the developer's canonical identity.
 Documentation
 -------------
 
-Developer Documentation
+Narrative Documentation
 ~~~~~~~~~~~~~~~~~~~~~~~
 
-OpenStack projects use Sphinx to produce project documentation from
-in-tree sources in ``doc/source`` and the HTML output in ``doc/build``.
+In order to reuse existing templates, styles, and tooling, OpenStack uses
+Sphinx to generate our Narrative Project documentation.
+
+In addition to the normal PTI :ref:`pti-documentation` requirements, for
+developer convenience, Go projects are recommended to provide:
 
     :code:`make docs`
         Generate HTML documentation from the in-tree developer docs
 
-If the project contains a ``setup.py`` file, it is expected that the ``docs``
-target will pass through to the equivalent to ``python setup.py build_sphinx``.
-If no ``setup.py`` is present the equivalent of ``make -f doc/Makefile html``
-will be executed.
+that should:
+
+* Either install any needed distro dependencies from the ``doc`` tag in
+  ``bindep.txt`` or emit an error if they are not installed.
+* Install Python dependencies for Sphinx from ``doc/requirements.txt``.
+* Execute ``sphinx-build -b html doc/source doc/build``
 
 Source
 ~~~~~~
@@ -239,14 +244,6 @@ A common translation process is not yet well-defined in the golang community.
 This section will be completed once a process is developed that is compatible
 with the existing OpenStack translation workflow.
 
-Release Tools
--------------
-
-OpenStack release tooling uses ``setup.py`` as an interface for the release
-process.  It is expected that golang projects will also use ``setup.py`` for
-some of its interface to these tools, however it may be desirable to investigate
-alternate interfaces if Sphinx docs are the only primary use otherwise.
-
 Build Tools
 -----------
 

reference/pti/javascript.rst

@@ -140,8 +140,22 @@ Generate Documentation
 :Command: :code:`npm run document`
 
 In order to reuse existing templates, styles, and tooling, OpenStack uses
-Sphinx to generate our JavaScript Project documentation. All documentation
-output should be placed in the :code:`publish-docs` directory.
+Sphinx to generate our JavaScript Project documentation.
+
+In addition to the normal PTI :ref:`pti-documentation` requirements, Javascript
+projects are recommended to provide an :code:`npm run document` command for
+developer convenience that should:
+
+* Either install any needed distro dependencies from the ``doc`` tag in
+  ``bindep.txt`` or emit an error if they are not installed.
+* Install Python dependencies for Sphinx from ``doc/requirements.txt``.
+* Execute ``sphinx-build -b html doc/source doc/build``
+
+The project infrastructure will not use ``npm`` to build the documentation.
+Therefore it is **STRONGLY** discouraged for people to put additional logic
+into the :code:`npm run document` command. Additional logic needed around
+Sphinx generation should go into Sphinx plugins which should be listed in
+``doc/requirements.txt``.
 
 .. _NPM package scripts: https://docs.npmjs.com/misc/scripts
 .. _ESLint: http://eslint.org

reference/pti/python.rst

@@ -110,8 +110,25 @@ files in to $project/locale as well.
 Documentation
 -------------
 
-Developer docs are generated from Sphinx sources in the tree. Additionally,
-there are end user docs and API docs which are maintained outside of the
-context of a project's repo. To support documentation generation, projects
-should have sphinx documentation source in doc/source and build_sphinx should
-output the documentation to doc/build.
+In addition to the normal PTI :ref:`pti-documentation` requirements, Python
+projects should put the following into their setup.cfg so that
+``python setup.py build_sphinx`` continues to work:
+
+::
+
+  [build_sphinx]
+  source-dir = doc/source
+  build-dir = doc/build
+
+It may be assumed that the project will be installed before Sphinx is run
+using ``pip install .``.
+
+As a convenience for developers, it is recommended that projects provide
+a ``docs`` environment for tox that will run either
+``sphinx-build -b html doc/source doc/build`` or
+``python setup.py build_sphinx``.
+
+The project infrastructure will not use ``tox -edocs`` to build the
+documentation. Therefore it is **STRONGLY** discouraged for people to put
+additional logic into the command section of that tox environment. Additional
+logic needed around Sphinx generation should go into Sphinx plugins.