Browse Source

docs: Use definition lists

These are far more concise and easier to read.

Change-Id: I411685b6e7d5385386b40cbf4b8bd4445b3c6847
tags/3.0.0
Stephen Finucane 2 years ago
parent
commit
54fb6e71b7
1 changed files with 70 additions and 51 deletions
  1. 70
    51
      doc/source/index.rst

+ 70
- 51
doc/source/index.rst View File

@@ -217,12 +217,12 @@ itself)::
217 217
     pbr.config.drivers =
218 218
         plain = pbr.cfg.driver:Plain
219 219
 
220
-pbr provides its own section in these documents, ostensibly called `pbr`, and
221
-provides a custom version of Sphinx's `build_sphinx` section. Most other
220
+`pbr` provides its own section in these documents, ostensibly called ``pbr``,
221
+and provides a custom version of Sphinx's ``build_sphinx`` section. Most other
222 222
 sections are provided by setuptools and may influence either the build itself
223 223
 or the output of various `setuptools commands`__. The remaining sections are
224 224
 provided 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 227
 __ https://setuptools.readthedocs.io/en/latest/setuptools.html#command-reference
228 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
250 250
 using three fundamental keys: ``packages``, ``namespace_packages``, and
251 251
 ``data_files``.
252 252
 
253
-``packages`` is a list of top-level packages that should be installed. The
254
-behavior of packages is similar to ``setuptools.find_packages`` in that it
255
-recurses the python package hierarchy below the given top level and installs
256
-all of it. If ``packages`` is not specified, it defaults to the value of the
257
-``name`` field given in the ``[metadata]`` section.
258
-
259
-``namespace_packages`` is the same, but is a list of packages that provide
260
-namespace packages.
261
-
262
-``data_files`` lists files to be installed. The format is an indented block
263
-that contains key value pairs which specify target directory and source file
264
-to install there. More than one source file for a directory may be indicated
265
-with a further indented list. Source files are stripped of leading directories.
266
-Additionally, `pbr` supports a simple file globbing syntax for installing
267
-entire directory structures, thus::
268
-
269
- [files]
270
- data_files =
271
-     etc/pbr = etc/pbr/*
272
-     etc/neutron =
273
-         etc/api-paste.ini
274
-         etc/dhcp-agent.ini
275
-     etc/init.d = neutron.init
276
-
277
-will result in `/etc/neutron` containing `api-paste.ini` and `dhcp-agent.ini`,
278
-both of which pbr will expect to find in the `etc` directory in the root of
279
-the source tree. Additionally, `neutron.init` from that dir will be installed
280
-in `/etc/init.d`. All of the files and directories located under `etc/pbr` in
281
-the source tree will be installed into `/etc/pbr`.
282
-
283
-Note that this behavior is relative to the effective root of the environment
284
-into which the packages are installed, so depending on available permissions
285
-this could be the actual system-wide `/etc` directory or just a top-level `etc`
286
-subdirectory of a virtualenv.
253
+``packages``
254
+
255
+  A list of top-level packages that should be installed. The behavior of
256
+  packages is similar to ``setuptools.find_packages`` in that it recurses the
257
+  python package hierarchy below the given top level and installs all of it. If
258
+  ``packages`` is not specified, it defaults to the value of the ``name`` field
259
+  given in the ``[metadata]`` section.
260
+
261
+``namespace_packages``
262
+
263
+  Similar to ``packages``, but is a list of packages that provide namespace
264
+  packages.
265
+
266
+``data_files``
267
+
268
+  A list of files to be installed. The format is an indented block that
269
+  contains key value pairs which specify target directory and source file to
270
+  install there. More than one source file for a directory may be indicated
271
+  with a further indented list. Source files are stripped of leading
272
+  directories.  Additionally, `pbr` supports a simple file globbing syntax for
273
+  installing entire directory structures, thus::
274
+
275
+   [files]
276
+   data_files =
277
+       etc/pbr = etc/pbr/*
278
+       etc/neutron =
279
+           etc/api-paste.ini
280
+           etc/dhcp-agent.ini
281
+       etc/init.d = neutron.init
282
+
283
+  will result in `/etc/neutron` containing `api-paste.ini` and `dhcp-agent.ini`,
284
+  both of which pbr will expect to find in the `etc` directory in the root of
285
+  the source tree. Additionally, `neutron.init` from that dir will be installed
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
 
288 294
 pbr
289 295
 ~~~
290 296
 
291
-The ``pbr`` section controls pbr specific options and behaviours.
297
+The ``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
 
293
-The ``autodoc_tree_index_modules`` is a boolean option controlling whether pbr
294
-should 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
297
-information.
319
+``autodoc_exclude_modules``
298 320
 
299
-The ``autodoc_index_modules`` is a boolean option controlling whether `pbr`
300
-should itself generates documentation for Python modules of the project. By
301
-default, all found Python modules are included; some of them can be excluded
302
-by listing them in ``autodoc_exclude_modules``. This list of modules can
303
-contains `fnmatch` style pattern (e.g. `myapp.tests.*`) to exclude some modules.
321
+  A list of modules to exclude when building module documentation using `pbr`.
322
+  `fnmatch` style pattern (e.g. `myapp.tests.*`) can be used.
304 323
 
305 324
 .. note::
306 325
 
@@ -448,11 +467,11 @@ environment, you can use::
448 467
 Testing
449 468
 -------
450 469
 
451
-pbr overrides the ``setuptools`` hook ``test`` (i.e. ``setup.py
452
-test``).  The following sequence is followed:
470
+`pbr` overrides the ``setuptools`` hook ``test`` (i.e. ``setup.py test``). The
471
+following sequence is followed:
453 472
 
454 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 475
    will use it as the test runner.  See the ``testr`` documentation
457 476
    for more details.
458 477
 

Loading…
Cancel
Save