Fix all sphinx errors & warnings

* tripleo-docs now passes sphinx-build -W test.
* Remove unneeded files.
* Don't mix toctree with includes to avoid duplicate labels.
* Add a common file for link references shared across docs.
* Make cross-references work across files.
* Move upload_single_image

Change-Id: I319e0d4e4dd03b7f769d9d38ad2829d6cc9a679a
Depends-On: I839a593df2116264112a6060f1f306910cfba197

doc/source/advanced_deployment/advanced_deployment.rst

@@ -1,12 +0,0 @@
-Advanced Deployment
-===================
-
-In this chapter you will find advanced deployment of various |project| areas.
-
-
-.. toctree::
-
-   features
-   baremetal_nodes
-   backends
-   custom

doc/source/advanced_deployment/baremetal_nodes.rst

@@ -4,10 +4,8 @@ Baremetal Node Configuration
 Documentation on how to do advanced configuration of baremetal nodes in
 |project|.
 
-
 .. toctree::
 
-
    node_states
    root_device
    introspect_single_node

doc/source/basic_deployment/basic_deployment_cli.rst

@@ -256,7 +256,7 @@ Load the images into the undercloud Glance::
 
     openstack overcloud image upload
 
-To upload a single image, see :doc:`../advanced_deployment/upload_single_image`.
+To upload a single image, see :doc:`../post_deployment/upload_single_image`.
 
 Register Nodes
 --------------

doc/source/basic_deployment/repositories.rst

@@ -1,3 +1,5 @@
+:orphan:
+
 Repository Enablement
 =====================
 

doc/source/developer/tht_walkthrough/changes-puppet-tripleo.rst

@@ -1,6 +1,8 @@
 Updating puppet-tripleo
 -----------------------
 
+.. include:: ../../links.rst
+
 The puppet manifests that currently define overcloud node configuration are
 moved from the tripleo-heat-templates to new puppet-tripleo class definitions
 as part of the composable services approach. In next iterations, all service

doc/source/developer/tht_walkthrough/changes-tht.rst

@@ -1,6 +1,8 @@
 Updating tripleo-heat-templates
 -------------------------------
 
+.. include:: ../../links.rst
+
 This section will describe the changes needed for tripleo-heat-templates.
 
 Folder structure convention for tripleo-heat-templates

doc/source/developer/tht_walkthrough/introduction.rst

@@ -1,6 +1,8 @@
 Introduction
 ------------
 
+.. include:: ../../links.rst
+
 The initial scope of this tutorial is to create a brief walkthrough with some
 guidelines and naming conventions for future modules and features aligned with
 the composable services architecture. Regarding the example described in this

doc/source/developer/tht_walkthrough/tht_walkthrough.rst

@@ -1,9 +1,7 @@
 Composable services tutorial
 ============================
 
-.. _composable services architecture: https://blueprints.launchpad.net/tripleo/+spec/composable-services-within-roles
-.. _THT repository: https://github.com/openstack/tripleo-heat-templates/tree/master/puppet/services
-.. _puppet-tripleo repository: https://github.com/openstack/puppet-tripleo/tree/master/manifests/profile
+.. include:: ../../links.rst
 
 This guide will be a walkthrough related to how to add new services to a TripleO
 deployment through additions to the tripleo-heat-templates and puppet-tripleo
@@ -14,8 +12,11 @@ repositories, using part of the architecture defined in the `composable services
   No puppet manifests may be defined in the `THT repository`_, they
   should go to the `puppet-tripleo repository`_ instead.
 
-.. include:: introduction.rst
-.. include:: changes-tht.rst
-.. include:: changes-puppet-tripleo.rst
-.. include:: design-patterns.rst
-.. include:: summary.rst
+.. toctree::
+   :maxdepth: 2
+
+   introduction
+   changes-tht
+   changes-puppet-tripleo
+   design-patterns
+   summary

doc/source/environments/environments.rst

@@ -4,6 +4,8 @@ Environment Setup
 |project| can be used in baremetal as well as in virtual environments. This
 section contains instructions on how to setup your environments properly.
 
-.. include:: virtual.rst
-.. include:: baremetal.rst
+.. toctree::
+   :maxdepth: 2
 
+   virtual
+   baremetal

doc/source/introduction.rst

@@ -1,7 +0,0 @@
-Introduction
-============
-
-TripleO is a program aimed at installing, upgrading and operating OpenStack
-clouds using OpenStack's own cloud facilities as the foundations - building
-on nova, neutron and heat to automate fleet management at datacentre scale
-(and scaling down to as few as 2 machines).

doc/source/introduction/components.rst

@@ -374,7 +374,8 @@ command with consistent syntax and behaviour.
 **How to contribute**
 
 * python-openstackclient uses `tox <https://tox.readthedocs.org/en/latest/>`_
-  to manage the development environment, see `upstream documentation
+  to manage the development environment, see the
+  `python-openstackclient documentation
   <https://github.com/openstack/python-openstackclient/blob/master/README.rst>`_
   for details. Submit your changes via OpenStack Gerrit
   (see `OpenStack Developer's Guide`_).
@@ -395,7 +396,8 @@ like node introspection, overcloud image building and uploading, etc.
 **How to contribute**
 
 * python-tripleoclient uses `tox <https://tox.readthedocs.org/en/latest/>`_
-  to manage the development environment, see `documentation
+  to manage the development environment, see the
+  `python-tripleoclient documentation
   <http://git.openstack.org/cgit/openstack/python-tripleoclient/tree/CONTRIBUTING.rst>`_
   for details. Submit your changes via
   `Gerrit <https://review.openstack.org/#/q/project:openstack/python-tripleoclient,n,z>`_.

doc/source/links.rst

@@ -0,0 +1,7 @@
+.. Links, citations, etc.
+.. _composable services architecture:
+    https://blueprints.launchpad.net/tripleo/+spec/composable-services-within-roles
+.. _THT repository:
+    https://github.com/openstack/tripleo-heat-templates/tree/master/puppet/services
+.. _puppet-tripleo repository:
+    https://github.com/openstack/puppet-tripleo/tree/master/manifests/profile

doc/source/post_deployment/post_deployment.rst

@@ -15,4 +15,5 @@ In this chapter you will find advanced management of various |project| areas.
    package_update
    upgrade
    build_single_image
+   upload_single_image
    backup_restore_undercloud

doc/source/troubleshooting/troubleshooting-nodes.rst

@@ -71,15 +71,17 @@ ironic-inspector times out introspection process after some time (defaulting to
 1 hour) if it never gets response from the introspection ramdisk.  This can be
 a sign of a bug in the introspection ramdisk, but usually it happens due to
 environment misconfiguration, particularly BIOS boot settings. Please refer to
-`ironic-inspector troubleshooting documentation`_ for information on how to
-detect and fix such problems.
+`ironic-inspector troubleshooting documentation
+<http://docs.openstack.org/developer/ironic-inspector/troubleshooting.html>`_
+for information on how to detect and fix such problems.
 
 Accessing the ramdisk
 ~~~~~~~~~~~~~~~~~~~~~
 
-Note that the introspection ramdisk is by default built with `the
-dynamic-login element`_, so you can set up an SSH key and log into it for
-debugging.
+Note that the introspection ramdisk is by default built with the
+`dynamic-login element
+<http://docs.openstack.org/developer/diskimage-builder/elements/dynamic-login/README.html>`_,
+so you can set up an SSH key and log into it for debugging.
 
 First, think of a temporary root password. Generate a hash by feeding it
 into ``openssl passwd -1`` command. Edit ``/httpboot/inspector.ipxe``

doc/source/troubleshooting/troubleshooting.rst

@@ -4,9 +4,11 @@ Troubleshooting
 At this chapter you will find answers for frequently asked questions and
 help with troubleshooting when using |project|.
 
+.. toctree::
+   :maxdepth: 2
 
-.. include:: troubleshooting-virt-setup.rst
-.. include:: troubleshooting-image-build.rst
-.. include:: troubleshooting-nodes.rst
-.. include:: troubleshooting-overcloud.rst
-.. include:: troubleshooting-tripleo-heat-templates.rst
+   troubleshooting-virt-setup
+   troubleshooting-image-build
+   troubleshooting-nodes
+   troubleshooting-overcloud
+   troubleshooting-tripleo-heat-templates