From f323413992737711bbc6c5b0d89c08b03d69d576 Mon Sep 17 00:00:00 2001 From: Doug Hellmann Date: Thu, 22 Jun 2017 15:56:49 -0400 Subject: [PATCH] turn on warning-as-error flag for doc build Change-Id: I5566cfa09dac8dec7a1bc32d95b42d5b136d726f Signed-off-by: Doug Hellmann --- doc/source/index.rst | 7 ------ doc/source/user/features.rst | 6 +++-- doc/source/user/using.rst | 46 +++++++++++++++++++++++------------- setup.cfg | 3 +-- 4 files changed, 35 insertions(+), 27 deletions(-) diff --git a/doc/source/index.rst b/doc/source/index.rst index 4de25fe0..309ff71e 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -43,10 +43,3 @@ Indices and tables * :ref:`modindex` * :ref:`search` -.. _"extra" requirements: - https://www.python.org/dev/peps/pep-0426/#extras-optional-dependencies -.. _conditional dependencies: - https://www.python.org/dev/peps/pep-0426/#environment-markers -.. _distutils2: http://alexis.notmyidea.org/distutils2/setupcfg.html -.. _sphinx-apidoc man page: http://sphinx-doc.org/man/sphinx-apidoc.html -.. _Sphinx build configuration file: http://sphinx-doc.org/config.html diff --git a/doc/source/user/features.rst b/doc/source/user/features.rst index 7eb88e9c..2a4c25c8 100644 --- a/doc/source/user/features.rst +++ b/doc/source/user/features.rst @@ -81,7 +81,8 @@ Sphinx documentation setups are altered to generate man pages by default. They also have several pieces of information that are known to setup.py injected into the sphinx config. -See the pbr_ section for details on configuring your project for autodoc. +See the :ref:`pbr-setup-cfg` section of the configuration file for +details on configuring your project for autodoc. Requirements ------------ @@ -101,7 +102,8 @@ If you want to have a different package list for Python 3 then just drop a `requirements-py3.txt` and it will be used instead. Finally, it is possible to specify groups of optional dependencies, or -`"extra" requirements`_, in your `setup.cfg` rather than `setup.py`. +:ref:`"extra" requirements `, in your `setup.cfg` +rather than `setup.py`. long_description ---------------- diff --git a/doc/source/user/using.rst b/doc/source/user/using.rst index 93ad0430..9f7e6d6e 100644 --- a/doc/source/user/using.rst +++ b/doc/source/user/using.rst @@ -39,7 +39,11 @@ setup.cfg The `setup.cfg` file is an ini-like file that can mostly replace the `setup.py` file. It is based on the distutils2_ `setup.cfg` file. A simple sample can be found in `pbr`'s own `setup.cfg` (it uses its own machinery to install -itself):: +itself): + +.. _distutils2: http://alexis.notmyidea.org/distutils2/setupcfg.html + +:: [metadata] name = pbr @@ -80,13 +84,13 @@ itself):: `pbr` provides its own section in these documents, ostensibly called ``pbr``, and provides a custom version of Sphinx's ``build_sphinx`` section. Most other sections are provided by setuptools and may influence either the build itself -or the output of various `setuptools commands`__. The remaining sections are +or the output of various `setuptools commands`_. The remaining sections are provided by libraries that provide setuptools extensions, such as -``extract_mesages`` (provided by `Babel`__). Some of these are described below. +``extract_mesages`` (provided by Babel_). Some of these are described below. -__ https://setuptools.readthedocs.io/en/latest/setuptools.html#command-reference -__ http://babel.pocoo.org/en/latest/setup.html -__ http://www.sphinx-doc.org/en/stable/setuptools.html +.. _setuptools commands: https://setuptools.readthedocs.io/en/latest/setuptools.html#command-reference +.. _Babel: http://babel.pocoo.org/en/latest/setup.html +.. _setuptools: http://www.sphinx-doc.org/en/stable/setuptools.html .. note:: @@ -151,6 +155,8 @@ using three fundamental keys: ``packages``, ``namespace_packages``, and this could be the actual system-wide `/etc` directory or just a top-level `etc` subdirectory of a virtualenv. +.. _pbr-setup-cfg: + pbr ~~~ @@ -166,8 +172,10 @@ The ``pbr`` section controls `pbr` specific options and behaviours. ``autodoc_tree_excludes`` A list of modules to exclude when building documentation using - `sphinx-apidoc`. Defaults to ``[setup.py]``. Refer to the `sphinx-apidoc man - page`_ for more information. + `sphinx-apidoc`. Defaults to ``[setup.py]``. Refer to the + `sphinx-apidoc man page`_ for more information. + +.. _sphinx-apidoc man page: http://sphinx-doc.org/man/sphinx-apidoc.html ``autodoc_index_modules`` @@ -197,6 +205,8 @@ The ``pbr`` section controls `pbr` specific options and behaviours. set. See the `Sphinx build configuration file`_ documentation for more information on configuring Sphinx. +.. _Sphinx build configuration file: http://sphinx-doc.org/config.html + .. versionchanged:: 2.0 The ``pbr`` section used to take a ``warnerrors`` option that would enable @@ -211,7 +221,7 @@ The ``build_sphinx`` section is a version of the ``build_sphinx`` setuptools plugin provided with Sphinx. This plugin extends the original plugin to add the following: -- Automatic generation of module documentation using the apidoc__ tool +- Automatic generation of module documentation using the apidoc tool - Automatic configuration of the `project`, `version` and `release` settings using information from `pbr` itself @@ -246,7 +256,7 @@ option. is. For information on the remaining options, refer to the `Sphinx -documentation`__. In addition, the ``autodoc_index_modules``, +documentation`_. In addition, the ``autodoc_index_modules``, ``autodoc_tree_index_modules``, ``autodoc_exclude_modules`` and ``autodoc_tree_excludes`` options in the ``pbr`` section will affect the output of the automatic module documentation generation. @@ -257,14 +267,13 @@ of the automatic module documentation generation. page output. This is no longer the case, and you should explicitly set ``builders`` to ``html man`` if you wish to retain this behavior. -__ http://www.sphinx-doc.org/en/stable/man/sphinx-apidoc.html -__ http://www.sphinx-doc.org/en/stable/setuptools.html +.. _Sphinx documentation: http://www.sphinx-doc.org/en/stable/man/sphinx-apidoc.html entry_points ~~~~~~~~~~~~ The ``entry_points`` section defines entry points for generated console scripts -and python libraries. This is actually provided by `setuptools`__ but is +and python libraries. This is actually provided by setuptools_ but is documented here owing to its importance. The general syntax of specifying entry points is a top level name indicating @@ -284,8 +293,6 @@ installed for `pbr.config.drivers`, one called `plain` which maps to the `Plain` class in `pbr.cfg.driver` and one called `fancy` which maps to the `Fancy` class in `pbr.cfg.driver`. -__ https://setuptools.readthedocs.io/en/latest/setuptools.html#options - Requirements ------------ @@ -305,6 +312,8 @@ Only the first file found is used to install the list of packages it contains. The 'requirements-pyN.txt' file is deprecated - 'requirements.txt' should be universal. You can use `Environment markers`_ for this purpose. +.. _extra-requirements: + Extra requirements ~~~~~~~~~~~~~~~~~~ @@ -312,6 +321,9 @@ Groups of optional dependencies, or `"extra" requirements`_, can be described in your `setup.cfg`, rather than needing to be added to `setup.py`. An example (which also demonstrates the use of environment markers) is shown below. +.. _"extra" requirements: + https://www.python.org/dev/peps/pep-0426/#extras-optional-dependencies + Environment markers ~~~~~~~~~~~~~~~~~~~ @@ -321,6 +333,9 @@ on the environment the installer is running in. They can be added to requirements in the requirements file, or to extras defined in `setup.cfg`, but the format is slightly different for each. +.. _conditional dependencies: + https://www.python.org/dev/peps/pep-0426/#environment-markers + For ``requirements.txt``:: argparse; python_version=='2.6' @@ -388,6 +403,5 @@ produce a coverage report. ``--coverage-package-name`` can be used to modify or narrow the packages traced. .. _d2to1: https://pypi.python.org/pypi/d2to1 -.. _distutils2: https://pypi.python.org/pypi/Distutils2 .. _PEP 426: http://legacy.python.org/dev/peps/pep-0426/ .. _OpenStack: https://www.openstack.org/ diff --git a/setup.cfg b/setup.cfg index a2aa5714..f842c9c3 100644 --- a/setup.cfg +++ b/setup.cfg @@ -51,8 +51,7 @@ console_scripts = all-files = 1 build-dir = doc/build source-dir = doc/source -# enable the below once Sphinx is bumped to 1.5.0+ in g-r -# warning-is-error = 1 +warning-is-error = 1 [wheel] universal = 1