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
This commit is contained in:
parent
2678231163
commit
2c0cdd2738
|
@ -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`_)
|
||||
|
|
|
@ -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
|
||||
-----------
|
||||
|
||||
|
|
|
@ -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
|
||||
|
|
|
@ -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.
|
||||
|
|
Loading…
Reference in New Issue