doc: Add documentation for missing '[pbr]' options

There are more that just autodoc options in here. Some formatting issues
are also corrected.

Change-Id: I075281d97c2fc7981a38ff1ddbb4ec76717ac726
Signed-off-by: Stephen Finucane <sfinucan@redhat.com>

2 files changed, 27 insertions, 7 deletions

diff --git a/doc/source/user/packagers.rst b/doc/source/user/packagers.rst
index 22c7687..74af8ac 100644
--- a/doc/source/user/packagers.rst
+++ b/doc/source/user/packagers.rst
@@ -59,6 +59,8 @@ requirements.
    don't want to debug or support the interactions that can occur when using
    it.
 
+.. _packaging-tarballs:
+
 Tarballs
 --------
 
@@ -78,6 +80,8 @@ automatically find all of the files, most of them do not have a complete
 ``MANIFEST.in`` file, so its possible that a tarball produced in that way will
 be missing files.
 
+.. _packaging-authors-changelog:
+
 AUTHORS and ChangeLog
 ---------------------
 
diff --git a/doc/source/user/using.rst b/doc/source/user/using.rst
index f8da6de..d160789 100644
--- a/doc/source/user/using.rst
+++ b/doc/source/user/using.rst
@@ -209,35 +209,51 @@ the ``Fancy`` class in ``pbr.cfg.driver``.
 
 The ``pbr`` section controls *pbr*-specific options and behaviours.
 
-``autodoc_tree_index_modules``
+``skip_git_sdist``
+  If enabled, *pbr* will not generate a manifest file from *git* commits. If
+  this is enabled, you may need to define your own `manifest template`__.
+
+  This can also be configured using the ``SKIP_GIT_SDIST`` environment
+  variable, as described :ref:`here <packaging-tarballs>`.
+
+  __ https://packaging.python.org/tutorials/distributing-packages/#manifest-in
+
+``skip_changelog``
+  If enabled, *pbr* will not generated a ``ChangeLog`` file from *git* commits.
+
+  This can also be configured using the ``SKIP_WRITE_GIT_CHANGELOG``
+  environment variable, as described :ref:`here <packaging-authors-changelog>`
+
+``skip_authors``
+  If enabled, *pbr* will not generate an ``AUTHORS`` file from *git* commits.
 
+  This can also be configured using the ``SKIP_GENERATE_AUTHORS`` environment
+  variable, as described :ref:`here <packaging-authors-changelog>`
+
+``autodoc_tree_index_modules``
   A boolean option controlling whether *pbr* should generate an index of
   modules using ``sphinx-apidoc``. By default, all files except ``setup.py``
   are included, but this can be overridden using the ``autodoc_tree_excludes``
   option.
 
 ``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.
 
-__ http://sphinx-doc.org/man/sphinx-apidoc.html
+  __ http://sphinx-doc.org/man/sphinx-apidoc.html
 
 ``autodoc_index_modules``
-
   A boolean option controlling whether *pbr* should itself generates
   documentation for Python modules of the project. By default, all found Python
   modules are included; some of them can be excluded by listing them in
   ``autodoc_exclude_modules``.
 
 ``autodoc_exclude_modules``
-
   A list of modules to exclude when building module documentation using *pbr*.
   *fnmatch* style pattern (e.g. ``myapp.tests.*``) can be used.
 
 ``api_doc_dir``
-
   A subdirectory inside the ``build_sphinx.source_dir`` where auto-generated
   API documentation should be written, if ``autodoc_index_modules`` is set to
   True. Defaults to ``"api"``.
@@ -252,7 +268,7 @@ __ http://sphinx-doc.org/man/sphinx-apidoc.html
    set. See the `Sphinx build configuration file`__ documentation for more
    information on configuring Sphinx.
 
-__ http://sphinx-doc.org/config.html
+   __ http://sphinx-doc.org/config.html
 
 .. versionchanged:: 2.0