doc: Fix formatting of packagers guide

We're going to be making some changes to this shortly.

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

1 files changed, 41 insertions, 38 deletions

diff --git a/doc/source/user/packagers.rst b/doc/source/user/packagers.rst
index a8faa31..22c7687 100644
--- a/doc/source/user/packagers.rst
+++ b/doc/source/user/packagers.rst
@@ -2,21 +2,21 @@
  Notes for Package maintainers
 ===============================
 
-If you are maintaining packages of software that uses `pbr`, there are some
+If you are maintaining packages of software that uses *pbr*, there are some
 features you probably want to be aware of that can make your life easier.
 They are exposed by environment variables, so adding them to rules or spec
 files should be fairly easy.
 
 Versioning
-==========
+----------
 
-`pbr`, when run in a git repo, derives the version of a package from the
+*pbr*, when run in a git repo, derives the version of a package from the
 git tags. When run in a tarball with a proper egg-info dir, it will happily
 pull the version from that. So for the most part, the package maintainers
 shouldn't need to care. However, if you are doing something like keeping a
 git repo with the sources and the packaging intermixed and it's causing pbr
 to get confused about whether its in its own git repo or not, you can set
-`PBR_VERSION`:
+``PBR_VERSION``:
 
 ::
 
@@ -26,73 +26,76 @@ and all version calculation logic will be completely skipped and the supplied
 version will be considered absolute.
 
 Distribution version numbers
-============================
-
-`pbr` will automatically calculate upstream version numbers for dpkg and rpm
-using systems. Releases are easy (and obvious). When packaging preleases though
-things get more complex. Firstly, semver does not provide for any sort order
-between pre-releases and development snapshots, so it can be complex (perhaps
-intractable) to package both into one repository - we recommend with either
-packaging pre-release releases (alpha/beta/rc's) or dev snapshots but not both.
-Secondly, as pre-releases and snapshots have the same major/minor/patch version
-as the version they lead up to, but have to sort before it, we cannot map their
-version naturally into the rpm version namespace: instead we represent their
-versions as versions of the release before.
+----------------------------
+
+*pbr* will automatically calculate upstream version numbers for *dpkg* and
+*rpm* using systems. Releases are easy (and obvious). When packaging
+pre-releases though things get more complex. Firstly, semver does not provide
+for any sort order between pre-releases and development snapshots, so it can be
+complex (perhaps intractable) to package both into one repository - we
+recommend with either packaging pre-release releases (alpha/beta/rc's) or dev
+snapshots but not both.  Secondly, as pre-releases and snapshots have the same
+major/minor/patch version as the version they lead up to, but have to sort
+before it, we cannot map their version naturally into the rpm version
+namespace: instead we represent their versions as versions of the release
+before.
 
 Dependencies
-============
+------------
 
-As of 1.0.0 `pbr` doesn't alter the dependency behaviour of `setuptools`.
+As of 1.0.0 *pbr* doesn't alter the dependency behaviour of *setuptools*.
 
-Older versions would invoke `pip` internally under some circumstances and
-required the environment variable `SKIP_PIP_INSTALL` to be set to prevent
+Older versions would invoke *pip* internally under some circumstances and
+required the environment variable ``SKIP_PIP_INSTALL`` to be set to prevent
 that. Since 1.0.0 we now document that dependencies should be installed before
-installing a `pbr` using package. We don't support easy install, but neither
+installing a *pbr* using package. We don't support easy install, but neither
 do we interfere with it today. If you observe easy install being triggered when
 building a binary package, then you've probably missed one or more package
 requirements.
 
-Note: we reserve the right to disable easy install via `pbr` in future, since
-we don't want to debug or support the interactions that can occur when using
-it.
+.. important::
+
+   We reserve the right to disable easy install via *pbr* in future, since we
+   don't want to debug or support the interactions that can occur when using
+   it.
 
 Tarballs
-========
+--------
 
-`pbr` includes everything in a source tarball that is in the original `git`
+*pbr* includes everything in a source tarball that is in the original *git*
 repository. This can again cause havoc if a package maintainer is doing fancy
-things with combined `git` repos, and is generating a source tarball using
-`python setup.py sdist` from that repo. If that is the workflow the packager
-is using, setting `SKIP_GIT_SDIST`:
+things with combined *git* repos, and is generating a source tarball using
+``python setup.py sdist`` from that repo. If that is the workflow the packager
+is using, setting ``SKIP_GIT_SDIST``:
 
 ::
 
   export SKIP_GIT_SDIST=1
 
 will cause all logic around using git to find the files that should be in the
-source tarball to be skipped. Beware though, that because `pbr` packages
+source tarball to be skipped. Beware though, that because *pbr* packages
 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
+``MANIFEST.in`` file, so its possible that a tarball produced in that way will
 be missing files.
 
 AUTHORS and ChangeLog
-=====================
+---------------------
 
-`pbr` generates AUTHORS and ChangeLog files from git information. This
-can cause problem in distro packaging if package maintainer is using git
+*pbr* generates ``AUTHORS`` and ``ChangeLog`` files from *git* information.
+This can cause problem in distro packaging if package maintainer is using *git*
 repository for packaging source. If that is the case setting
-`SKIP_GENERATE_AUTHORS`
+``SKIP_GENERATE_AUTHORS``
 
 ::
 
    export SKIP_GENERATE_AUTHORS=1
 
-will cause logic around generating AUTHORS using git information to be
-skipped. Similarly setting `SKIP_WRITE_GIT_CHANGELOG`
+will cause logic around generating ``AUTHORS`` using *git* information to be
+skipped. Similarly setting ``SKIP_WRITE_GIT_CHANGELOG``
 
 ::
 
    export SKIP_WRITE_GIT_CHANGELOG=1
 
-will cause logic around generating ChangeLog file using git
+will cause logic around generating ``ChangeLog`` file using *git*
 information to be skipped.