From 2c0cdd2738310285e8ab363463fd4f10d7fca9c1 Mon Sep 17 00:00:00 2001 From: Monty Taylor Date: Sat, 30 Sep 2017 09:23:31 -0500 Subject: [PATCH] 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 | 38 +++++++++++++++++++++++++ reference/pti/golang.rst | 27 ++++++++---------- reference/pti/javascript.rst | 18 ++++++++++-- reference/pti/python.rst | 27 ++++++++++++++---- 4 files changed, 88 insertions(+), 22 deletions(-) diff --git a/reference/project-testing-interface.rst b/reference/project-testing-interface.rst index 54f758dff..87cedef16 100644 --- a/reference/project-testing-interface.rst +++ b/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`_) diff --git a/reference/pti/golang.rst b/reference/pti/golang.rst index fad73a2ea..48fea3245 100644 --- a/reference/pti/golang.rst +++ b/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 ----------- diff --git a/reference/pti/javascript.rst b/reference/pti/javascript.rst index 5f1261d8d..3c3c75e10 100644 --- a/reference/pti/javascript.rst +++ b/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 diff --git a/reference/pti/python.rst b/reference/pti/python.rst index d0bff9f95..e1a059b94 100644 --- a/reference/pti/python.rst +++ b/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.