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
|
Tools and approaches vary by language, please choose which language is
|
||||||
relevant to you.
|
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:
|
The following operating systems are the most popular when deploying OpenStack:
|
||||||
|
|
||||||
- Ubuntu (`latest LTS`_)
|
- Ubuntu (`latest LTS`_)
|
||||||
|
|
|
@ -194,19 +194,24 @@ address or identity, and should map to the developer's canonical identity.
|
||||||
Documentation
|
Documentation
|
||||||
-------------
|
-------------
|
||||||
|
|
||||||
Developer Documentation
|
Narrative Documentation
|
||||||
~~~~~~~~~~~~~~~~~~~~~~~
|
~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
OpenStack projects use Sphinx to produce project documentation from
|
In order to reuse existing templates, styles, and tooling, OpenStack uses
|
||||||
in-tree sources in ``doc/source`` and the HTML output in ``doc/build``.
|
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`
|
:code:`make docs`
|
||||||
Generate HTML documentation from the in-tree developer docs
|
Generate HTML documentation from the in-tree developer docs
|
||||||
|
|
||||||
If the project contains a ``setup.py`` file, it is expected that the ``docs``
|
that should:
|
||||||
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``
|
* Either install any needed distro dependencies from the ``doc`` tag in
|
||||||
will be executed.
|
``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
|
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
|
This section will be completed once a process is developed that is compatible
|
||||||
with the existing OpenStack translation workflow.
|
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
|
Build Tools
|
||||||
-----------
|
-----------
|
||||||
|
|
||||||
|
|
|
@ -140,8 +140,22 @@ Generate Documentation
|
||||||
:Command: :code:`npm run document`
|
:Command: :code:`npm run document`
|
||||||
|
|
||||||
In order to reuse existing templates, styles, and tooling, OpenStack uses
|
In order to reuse existing templates, styles, and tooling, OpenStack uses
|
||||||
Sphinx to generate our JavaScript Project documentation. All documentation
|
Sphinx to generate our JavaScript Project documentation.
|
||||||
output should be placed in the :code:`publish-docs` directory.
|
|
||||||
|
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
|
.. _NPM package scripts: https://docs.npmjs.com/misc/scripts
|
||||||
.. _ESLint: http://eslint.org
|
.. _ESLint: http://eslint.org
|
||||||
|
|
|
@ -110,8 +110,25 @@ files in to $project/locale as well.
|
||||||
Documentation
|
Documentation
|
||||||
-------------
|
-------------
|
||||||
|
|
||||||
Developer docs are generated from Sphinx sources in the tree. Additionally,
|
In addition to the normal PTI :ref:`pti-documentation` requirements, Python
|
||||||
there are end user docs and API docs which are maintained outside of the
|
projects should put the following into their setup.cfg so that
|
||||||
context of a project's repo. To support documentation generation, projects
|
``python setup.py build_sphinx`` continues to work:
|
||||||
should have sphinx documentation source in doc/source and build_sphinx should
|
|
||||||
output the documentation to doc/build.
|
::
|
||||||
|
|
||||||
|
[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