Turn docs warnings into errors and fix issues

Set the pbr option 'warnerrors' to make build_sphinx turns warnings into
error. Fix all warnings.

`tox -edocs` will thus abort whenever someone introduce a new error.

Change-Id: Id6d09768a241866e1fdc1a1e2bf90336f5c5087d

doc/source/conf.py

@@ -105,7 +105,7 @@ html_theme = 'default'
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['_static']
+#html_static_path = ['_static']
 
 # Add any extra paths that contain custom files (such as robots.txt or
 # .htaccess) here, relative to this directory. These files are copied

doc/source/copyright.rst

@@ -2,6 +2,7 @@ Copyright
 =========
 
 Copyright 2012 Hewlett-Packard Development Company, L.P.
+
 Copyright (c) 2012 NTT DOCOMO, INC.
 
 All Rights Reserved.

doc/source/developer/components.rst

@@ -28,7 +28,7 @@ Components
 
     **DEPRECATED** Extract the appropriate kernel and ramdisk to use when doing
     PXE boot using filename as the image for a machine. Consider using the
-    :ref:`baremetal` element, rather than this tool.
+    :ref:`element-baremetal` element, rather than this tool.
 
 
 `element-info`

doc/source/developer/developing_elements.rst

@@ -185,7 +185,7 @@ possible approach to this would be to label elements as either a "driver",
 "service", or "config" element. Below are some examples.
 
 - Driver-specific elements should only contain the necessary bits for that
-  driver:
+  driver::
 
       elements/
          driver-mellanox/
@@ -194,7 +194,7 @@ possible approach to this would be to label elements as either a "driver",
                10-mlx      - package installation
 
 - An element that installs and configures Nova might be a bit more complex,
-  containing several scripts across several phases:
+  containing several scripts across several phases::
 
       elements/
          service-nova/

doc/source/index.rst

@@ -17,3 +17,4 @@ easier.
    user_guide/index
    developer/index
    elements
+   copyright

elements/baremetal/README.rst

@@ -1,3 +1,5 @@
+.. _element-baremetal:
+
 =========
 baremetal
 =========

elements/pkg-map/README.rst

@@ -5,22 +5,23 @@ Map package names to distro specific packages.
 
 Provides the following:
 
- * bin/pkg-map
+ * bin/pkg-map::
 
-   usage: pkg-map [-h] [--element ELEMENT] [--distro DISTRO]
+    usage: pkg-map [-h] [--element ELEMENT] [--distro DISTRO]
 
-   Translate package name to distro specific name.
+    Translate package name to distro specific name.
 
-   optional arguments:
-     -h, --help         show this help message and exit
-     --element ELEMENT  The element (namespace) to use for translation.
-     --distro DISTRO    The distro name to use for translation. Defaults to
-                        DISTRO_NAME
+    optional arguments:
+      -h, --help         show this help message and exit
+      --element ELEMENT  The element (namespace) to use for translation.
+      --distro DISTRO    The distro name to use for translation. Defaults to
+                         DISTRO_NAME
 
  * Any element may create its own pkg-map JSON config file using
    the one of 3 sections for the distro/family/ and or default.
    The family is set automatically within pkg-map based on
    the supplied distro name. Families include:
+
      + redhat: includes centos, fedora, and rhel distros
      + debian: includes debian and ubuntu distros
      + suse: includes the opensuse distro
@@ -31,7 +32,8 @@ Provides the following:
    for Fedora and package mapping for suse family to provide a good
    example!)
 
-   Example format:
+   Example format::
+
     {
       "distro": {
         "fedora": {

elements/rhel-common/README.rst

@@ -26,7 +26,7 @@ risk.
 
 IMPORTANT NOTE:
 ----------------
-The 00-rhsm script is specific to RHEL6.  If you use the REG_ variables to
+The 00-rhsm script is specific to RHEL6.  If you use the REG\_ variables to
 use with RHEL7, you do not need to set any DIB_RHSM variables.  The scripts
 named with "rhel-registration" have not been developed or tested for RHEL6.
 For information on building RHEL6 images, please see the rhel element README.
@@ -214,7 +214,7 @@ Heat metadata can be used to configure the rhel-common element.
 Configuration Registration Examples
 ------------------------------------
 To register with Satellite 6, a common example would be to use the following
-metadata:
+metadata::
 
     {
         "rh_registration":{
@@ -222,13 +222,13 @@ metadata:
             "org": "tripleo",
             "environment": "Library",
             "activation_key": "my-key-SQQkh4",
-            "method":"satellite"
+            "method":"satellite",
             "repos": "rhel-ha-for-rhel-7-server-rpms"
         }
     }
 
 To register with the Red Hat Customer Portal, a common example would be to
-use the following metadata:
+use the following metadata::
 
     {
         "rh_registration":{

elements/svc-map/README.rst

@@ -18,6 +18,7 @@ Provides the following:
    the one of 3 sections for the distro/family/ and or default.
    The family is set automatically within svc-map based on
    the supplied distro name. Families include:
+
      + redhat: includes centos, fedora, and rhel distros
      + debian: includes debian and ubuntu distros
      + suse: includes the opensuse distro
@@ -30,7 +31,7 @@ Provides the following:
    the source name against systemd and upstart and return that name if it
    exists instead of the mapped name.
 
-    Example format for Nova:
+    Example format for Nova::
 
       nova-api:
         default: openstack-nova-api
@@ -49,7 +50,7 @@ Provides the following:
         debian: nova-console
 
 
-    Example format for Glance
+    Example format for Glance::
 
       glance-api:
         debian: glance-api
@@ -59,7 +60,7 @@ Provides the following:
         default: openstack-glance-registry
 
 
-    If the distro is of the debian family the combined services file would be:
+    If the distro is of the debian family the combined services file would be::
 
         nova-cert: nova-cert
         nova-compute: nova-compute
@@ -70,7 +71,7 @@ Provides the following:
         nova-consoleauth: nova-console
 
 
-    If the distro is of the suse or redhat families the combined services file would be:
+    If the distro is of the suse or redhat families the combined services file would be::
 
         nova-cert: openstack-nova-cert
         nova-compute: openstack-nova-compute
@@ -81,19 +82,19 @@ Provides the following:
         nova-api: openstack-nova-api
 
 
-   Example commands using this format:
+   Example commands using this format::
 
-   svc-map nova-compute
+       svc-map nova-compute
 
-   Returns: openstack-nova-compute
+       Returns: openstack-nova-compute
 
-   svc-map nova-compute
+       svc-map nova-compute
 
-   Returns: openstack-nova-compute
+       Returns: openstack-nova-compute
 
-   svc-map nova-compute
+       svc-map nova-compute
 
-   Returns: nova-compute
+       Returns: nova-compute
 
  * This output can be used to filter what other tools actually install
    (install-services can be modified to use this for example)

setup.cfg

@@ -41,6 +41,9 @@ keywords = _ gettext ngettext l_ lazy_gettext
 mapping_file = babel.cfg
 output_file = diskimage_builder/locale/diskimage_builder.pot
 
+[pbr]
+warnerrors = True
+
 [update_catalog]
 domain = diskimage_builder
 output_dir = diskimage_builder/locale