summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorStephen Finucane <sfinucan@redhat.com>2017-04-12 11:20:02 +0100
committerStephen Finucane <sfinucan@redhat.com>2017-04-14 18:04:57 +0000
commit54fb6e71b71b8467352edd745399940444aac435 (patch)
tree09482e63fe61f39d77eaad28342c6eb68503c4a8
parent5da68b9894b13416d6e559a3063509f958d9efa7 (diff)
docs: Use definition lists
These are far more concise and easier to read. Change-Id: I411685b6e7d5385386b40cbf4b8bd4445b3c6847
Notes
Notes (review): Code-Review+2: Monty Taylor <mordred@inaugust.com> Code-Review+2: Julien Danjou <julien@danjou.info> Workflow+1: ChangBo Guo(gcb) <glongwave@gmail.com> Verified+2: Jenkins Submitted-by: Jenkins Submitted-at: Sat, 15 Apr 2017 14:36:53 +0000 Reviewed-on: https://review.openstack.org/456155 Project: openstack-dev/pbr Branch: refs/heads/master
-rw-r--r--doc/source/index.rst121
1 files changed, 70 insertions, 51 deletions
diff --git a/doc/source/index.rst b/doc/source/index.rst
index 65be4e2..4a4e90a 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -217,12 +217,12 @@ itself)::
217 pbr.config.drivers = 217 pbr.config.drivers =
218 plain = pbr.cfg.driver:Plain 218 plain = pbr.cfg.driver:Plain
219 219
220pbr provides its own section in these documents, ostensibly called `pbr`, and 220`pbr` provides its own section in these documents, ostensibly called ``pbr``,
221provides a custom version of Sphinx's `build_sphinx` section. Most other 221and provides a custom version of Sphinx's ``build_sphinx`` section. Most other
222sections are provided by setuptools and may influence either the build itself 222sections are provided by setuptools and may influence either the build itself
223or the output of various `setuptools commands`__. The remaining sections are 223or the output of various `setuptools commands`__. The remaining sections are
224provided by libraries that provide setuptools extensions, such as 224provided by libraries that provide setuptools extensions, such as
225`extract_mesages` (provided by `Babel`__). Some of these are described below. 225``extract_mesages`` (provided by `Babel`__). Some of these are described below.
226 226
227__ https://setuptools.readthedocs.io/en/latest/setuptools.html#command-reference 227__ https://setuptools.readthedocs.io/en/latest/setuptools.html#command-reference
228__ http://babel.pocoo.org/en/latest/setup.html 228__ http://babel.pocoo.org/en/latest/setup.html
@@ -250,57 +250,76 @@ The ``files`` section defines the install location of files in the package
250using three fundamental keys: ``packages``, ``namespace_packages``, and 250using three fundamental keys: ``packages``, ``namespace_packages``, and
251``data_files``. 251``data_files``.
252 252
253``packages`` is a list of top-level packages that should be installed. The 253``packages``
254behavior of packages is similar to ``setuptools.find_packages`` in that it 254
255recurses the python package hierarchy below the given top level and installs 255 A list of top-level packages that should be installed. The behavior of
256all of it. If ``packages`` is not specified, it defaults to the value of the 256 packages is similar to ``setuptools.find_packages`` in that it recurses the
257``name`` field given in the ``[metadata]`` section. 257 python package hierarchy below the given top level and installs all of it. If
258 258 ``packages`` is not specified, it defaults to the value of the ``name`` field
259``namespace_packages`` is the same, but is a list of packages that provide 259 given in the ``[metadata]`` section.
260namespace packages. 260
261 261``namespace_packages``
262``data_files`` lists files to be installed. The format is an indented block 262
263that contains key value pairs which specify target directory and source file 263 Similar to ``packages``, but is a list of packages that provide namespace
264to install there. More than one source file for a directory may be indicated 264 packages.
265with a further indented list. Source files are stripped of leading directories. 265
266Additionally, `pbr` supports a simple file globbing syntax for installing 266``data_files``
267entire directory structures, thus:: 267
268 268 A list of files to be installed. The format is an indented block that
269 [files] 269 contains key value pairs which specify target directory and source file to
270 data_files = 270 install there. More than one source file for a directory may be indicated
271 etc/pbr = etc/pbr/* 271 with a further indented list. Source files are stripped of leading
272 etc/neutron = 272 directories. Additionally, `pbr` supports a simple file globbing syntax for
273 etc/api-paste.ini 273 installing entire directory structures, thus::
274 etc/dhcp-agent.ini 274
275 etc/init.d = neutron.init 275 [files]
276 276 data_files =
277will result in `/etc/neutron` containing `api-paste.ini` and `dhcp-agent.ini`, 277 etc/pbr = etc/pbr/*
278both of which pbr will expect to find in the `etc` directory in the root of 278 etc/neutron =
279the source tree. Additionally, `neutron.init` from that dir will be installed 279 etc/api-paste.ini
280in `/etc/init.d`. All of the files and directories located under `etc/pbr` in 280 etc/dhcp-agent.ini
281the source tree will be installed into `/etc/pbr`. 281 etc/init.d = neutron.init
282 282
283Note that this behavior is relative to the effective root of the environment 283 will result in `/etc/neutron` containing `api-paste.ini` and `dhcp-agent.ini`,
284into which the packages are installed, so depending on available permissions 284 both of which pbr will expect to find in the `etc` directory in the root of
285this could be the actual system-wide `/etc` directory or just a top-level `etc` 285 the source tree. Additionally, `neutron.init` from that dir will be installed
286subdirectory of a virtualenv. 286 in `/etc/init.d`. All of the files and directories located under `etc/pbr` in
287 the source tree will be installed into `/etc/pbr`.
288
289 Note that this behavior is relative to the effective root of the environment
290 into which the packages are installed, so depending on available permissions
291 this could be the actual system-wide `/etc` directory or just a top-level
292 `etc` subdirectory of a virtualenv.
287 293
288pbr 294pbr
289~~~ 295~~~
290 296
291The ``pbr`` section controls pbr specific options and behaviours. 297The ``pbr`` section controls `pbr` specific options and behaviours.
298
299``autodoc_tree_index_modules``
300
301 A boolean option controlling whether `pbr` should generate an index of
302 modules using `sphinx-apidoc`. By default, all files except `setup.py` are
303 included, but this can be overridden using the ``autodoc_tree_excludes``
304 option.
305
306``autodoc_tree_excludes``
307
308 A list of modules to exclude when building documentation using
309 `sphinx-apidoc`. Defaults to ``[setup.py]``. Refer to the `sphinx-apidoc man
310 page`_ for more information.
311
312``autodoc_index_modules``
313
314 A boolean option controlling whether `pbr` should itself generates
315 documentation for Python modules of the project. By default, all found Python
316 modules are included; some of them can be excluded by listing them in
317 ``autodoc_exclude_modules``.
292 318
293The ``autodoc_tree_index_modules`` is a boolean option controlling whether pbr 319``autodoc_exclude_modules``
294should generate an index of modules using ``sphinx-apidoc``. By default,
295`setup.py` is excluded. The list of excluded modules can be specified with the
296``autodoc_tree_excludes`` option. See the `sphinx-apidoc man page`_ for more
297information.
298 320
299The ``autodoc_index_modules`` is a boolean option controlling whether `pbr` 321 A list of modules to exclude when building module documentation using `pbr`.
300should itself generates documentation for Python modules of the project. By 322 `fnmatch` style pattern (e.g. `myapp.tests.*`) can be used.
301default, all found Python modules are included; some of them can be excluded
302by listing them in ``autodoc_exclude_modules``. This list of modules can
303contains `fnmatch` style pattern (e.g. `myapp.tests.*`) to exclude some modules.
304 323
305.. note:: 324.. note::
306 325
@@ -448,11 +467,11 @@ environment, you can use::
448Testing 467Testing
449------- 468-------
450 469
451pbr overrides the ``setuptools`` hook ``test`` (i.e. ``setup.py 470`pbr` overrides the ``setuptools`` hook ``test`` (i.e. ``setup.py test``). The
452test``). The following sequence is followed: 471following sequence is followed:
453 472
454#. If a ``.testr.conf`` file exists and `testrepository 473#. If a ``.testr.conf`` file exists and `testrepository
455 <https://pypi.python.org/pypi/testrepository>`__ is installed, PBR 474 <https://pypi.python.org/pypi/testrepository>`__ is installed, `pbr`
456 will use it as the test runner. See the ``testr`` documentation 475 will use it as the test runner. See the ``testr`` documentation
457 for more details. 476 for more details.
458 477