March to the beat of the new docs drum

Boss drum, motivating rhythm of life with the
healing, rhythmic synergy.

More seriously, this patch re-arranges the
documentation structure to conform to the
structure outlined in [1].

With it, some changes are made to effectively
transition the links and simplify the sphinx
configuration.

The Mitaka/Liberty documentation links are
removed as they are no longer available.

[1] http://specs.openstack.org/openstack/docs-specs/specs/pike/os-manuals-migration.html
Change-Id: Icc985de3af4de5ea7a5aa01b6e6f6e524c67f11b

doc/source/admin/index.rst

@@ -6,7 +6,7 @@ This guide provides information about operating your OpenStack-Ansible
 deployment.
 
 For information how to deploy your OpenStack-Ansible cloud, refer to the
-`Deployment Guide <https://docs.openstack.org/project-deploy-guide/openstack-ansible/draft/>`_
+:deploy_guide:`Deployment Guide <index.html>`
 for step-by-step instructions on how to deploy the OpenStack packages and
 dependencies on your cloud using OpenStack-Ansible.
 

doc/source/admin/maintenance-tasks/network-maintain.rst

@@ -61,7 +61,7 @@ addressable name inside the Neutron configuration.
 This configuration also need to be unique across other provider networks.
 
 For more information, see
-`Configure the deployment <https://docs.openstack.org/project-deploy-guide/openstack-ansible/draft/configure.html>`_
+:deploy_guide:`Configure the deployment <configure.html>`
 in the OpenStack-Ansible Deployment Guide.
 
 OpenStack-Ansible playbooks

doc/source/conf.py

@@ -22,7 +22,6 @@
 # All configuration values have a default; values that are commented out
 # serve to show the default.
 
-import openstackdocstheme
 import os
 import pbr.version
 import sys
@@ -40,11 +39,15 @@ sys.path.insert(0, os.path.abspath('../../playbooks/inventory/'))
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-# TODO(ajaeger): enable PDF building, for example add 'rst2pdf.pdfbuilder'
-extensions = ['sphinx.ext.autodoc','sphinxmark', 'sphinx.ext.extlinks']
+extensions = [
+    'openstackdocstheme',
+    'sphinx.ext.autodoc',
+    'sphinx.ext.extlinks',
+    'sphinxmark'
+]
 
 # Add any paths that contain templates here, relative to this directory.
-# templates_path = ['_templates']
+templates_path = ['_templates']
 
 # The suffix of source filenames.
 source_suffix = '.rst'
@@ -58,7 +61,7 @@ master_doc = 'index'
 # General information about the project.
 author = 'OpenStack-Ansible Contributors'
 category = 'Miscellaneous'
-copyright = '2014-2016, OpenStack-Ansible Contributors'
+copyright = '2014-2017, OpenStack-Ansible Contributors'
 description = 'OpenStack-Ansible deploys OpenStack environments using Ansible.'
 project = 'OpenStack-Ansible'
 target_name = 'openstack-ansible'
@@ -75,23 +78,14 @@ release = version_info.version_string_with_vcs()
 # The short X.Y version.
 version = version_info.canonical_version_string()
 
-# A few variables have to be set for the log-a-bug feature.
-#   giturl: The location of conf.py on Git. Must be set manually.
-#   gitsha: The SHA checksum of the bug description. Automatically extracted from git log.
-#   bug_tag: Tag for categorizing the bug. Must be set manually.
-# These variables are passed to the logabug code via html_context.
-giturl = ("https://git.openstack.org/cgit/openstack/{0}"
-          "/tree/doc/source").format(target_name)
-git_cmd = "/usr/bin/git log | head -n1 | cut -f2 -d' '"
-gitsha = os.popen(git_cmd).read().strip('\n')
-bug_title = "Documentation bug"
-html_context = {"gitsha": gitsha, "giturl": giturl,
-                "bug_tag": "docs", "bug_title": bug_title,
-                "bug_project": target_name}
+# openstackdocstheme options
+repository_name = 'openstack/' + target_name
+bug_project = project.lower()
+bug_tag = ''
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
-# language = None
+language = None
 
 # There are two options for replacing |today|: either, you set today to some
 # non-false value, then it is used:
@@ -127,6 +121,10 @@ pygments_style = 'sphinx'
 # If true, keep warnings as "system message" paragraphs in the built documents.
 # keep_warnings = False
 
+# If true, `todo` and `todoList` produce output, else they produce nothing.
+todo_include_todos = False
+
+
 # -- Options for HTML output ----------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
@@ -139,7 +137,7 @@ html_theme = 'openstackdocs'
 # html_theme_options = {}
 
 # Add any paths that contain custom themes here, relative to this directory.
-html_theme_path = [openstackdocstheme.get_html_theme_path()]
+# html_theme_path = []
 
 # The name for this set of Sphinx documents.  If None, it defaults to
 # "<project> v<release> documentation".
@@ -160,7 +158,7 @@ html_theme_path = [openstackdocstheme.get_html_theme_path()]
 # 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 = []
+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
@@ -186,13 +184,13 @@ html_last_updated_fmt = '%Y-%m-%d %H:%M'
 # html_domain_indices = True
 
 # If false, no index is generated.
-html_use_index = False
+# html_use_index = True
 
 # If true, the index is split into individual pages for each letter.
 # html_split_index = False
 
 # If true, links to the reST sources are added to the pages.
-html_show_sourcelink = False
+# html_show_sourcelink = True
 
 # If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
 # html_show_sphinx = True
@@ -299,15 +297,18 @@ pdf_documents = [
      title, author)
 ]
 
+# Used for the developer documentation
 latest_tag = os.popen('git describe --abbrev=0 --tags').read().strip('\n')
 
+# Used for the upgrade documentation
 previous_release_branch_name = 'ocata'
 current_release_branch_name = 'pike'
+
 # dev docs have no branch specified on master; for stable braches it's "/branch/"
 watermark = os.popen("git branch --contains $(git rev-parse HEAD) | awk -F/ '/stable/ {print $2}'").read().strip(' \n\t').capitalize()
 if watermark == "":
     watermark = "Pre-release"
-    deploy_branch_link_name = "draft"
+    deploy_branch_link_name = "latest"
     dev_branch_link_name = ""
     current_release_git_branch_name = "master"
 else:
@@ -322,8 +323,9 @@ current_release_capital_name = current_release_branch_name.upper()
 current_release_formal_name = current_release_branch_name.capitalize()
 upgrade_backup_dir = "``/etc/openstack_deploy."+previous_release_capital_name+"``"
 
+# Used to reference the deploy guide
 deploy_guide_prefix = "http://docs.openstack.org/project-deploy-guide/openstack-ansible/{}/%s".format(deploy_branch_link_name)
-dev_docs_prefix = "http://docs.openstack.org/developer/openstack-ansible/developer-docs/{}%s".format(dev_branch_link_name)
+dev_docs_prefix = "http://docs.openstack.org/developer/openstack-ansible/{}%s".format(dev_branch_link_name)
 
 rst_epilog = """
 .. |previous_release_branch_name| replace:: %s

doc/source/contributor/index.rst

@@ -6,7 +6,7 @@ In this section, you will find documentation relevant to developing
 OpenStack-Ansible.
 
 For information on how to install and deploy OpenStack-Ansible, see the
-`Deployment Guide`_.
+:deploy_guide:`Deployment Guide <index.html>`.
 
 Contents:
 
@@ -21,4 +21,3 @@ Contents:
    core-reviewers
    role-services
 
-.. _Deployment Guide: https://docs.openstack.org/project-deploy-guide/openstack-ansible/draft/

doc/source/contributor/quickstart-aio.rst

@@ -69,7 +69,7 @@ system packages are upgraded and then reboot into the new kernel:
 
    If you are installing with limited connectivity, please review
    the *Installing with limited connectivity* appendix in the
-   `Deployment Guide`_ before proceeding.
+   :deploy_guide:`Deployment Guide <index.html>` before proceeding.
 
 Start by cloning the OpenStack-Ansible repository and changing into the
 repository root directory:
@@ -188,7 +188,7 @@ following:
 
 To add any global overrides, over and above the defaults for the applicable
 scenario, edit  ``/etc/openstack_deploy/user_variables.yml``. See the
-`Deployment Guide`_ for more details.
+:deploy_guide:`Deployment Guide <index.html>` for more details.
 
 Finally, run the playbooks by executing:
 
@@ -227,7 +227,6 @@ Keystone service, execute:
 that are not requested for deployment, but the service will not be deployed
 in that container.
 
-.. _Deployment Guide: http://docs.openstack.org/project-deploy-guide/openstack-ansible/draft/
 .. _bootstrap-aio default services: https://git.openstack.org/cgit/openstack/openstack-ansible/tree/tests/bootstrap-aio.yml
 
 Rebooting an AIO
@@ -243,9 +242,9 @@ This is done by executing the following:
    # openstack-ansible -e galera_ignore_cluster_state=true galera-install.yml
 
 If this fails to get the database cluster back into a running state, then
-please make use of the `Galera Cluster Recovery`_ page in the Install Guide.
-
-.. _Galera Cluster Recovery: http://docs.openstack.org/developer/openstack-ansible/draft-operations-guide/maintenance-tasks/galera.html#galera-cluster-recovery
+please make use of the
+:dev_docs:`Galera Cluster Recovery <admin/maintenance-tasks/galera.html>`
+section in the operations guide.
 
 Rebuilding an AIO
 -----------------

doc/source/index.rst

@@ -17,12 +17,12 @@ OpenStack-Ansible Pike is currently in development.
 .. toctree::
    :maxdepth: 1
 
-   Deployment Guide <https://docs.openstack.org/project-deploy-guide/openstack-ansible/draft/>
-   Release Notes <http://docs.openstack.org/releasenotes/openstack-ansible/unreleased.html>
-   operations-guide/index
-   upgrade-guide/index
-   developer-docs/index
-   inventory/index
+   :deploy_guide:Deployment Guide <index.html>
+   releasenotes/unreleased
+   admin/index
+   user/index
+   contributor/index
+   reference/index
 
 Ocata: Current stable release, security supported
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -34,7 +34,7 @@ OpenStack-Ansible's Ocata series was first released with the 15.0.0 tag on
 
 * `OpenStack-Ansible Ocata series release notes`_
 
-.. _OpenStack-Ansible Ocata Documentation: https://docs.openstack.org/openstack-ansible/ocata/ocata/
+.. _OpenStack-Ansible Ocata Documentation: https://docs.openstack.org/openstack-ansible/ocata/
 .. _OpenStack-Ansible Ocata series release notes: http://docs.openstack.org/releasenotes/openstack-ansible/ocata.html
 
 Newton: Current stable release, security supported
@@ -49,38 +49,6 @@ OpenStack-Ansible's Newton series was first released with the 14.0.0 tag on
 
 * `OpenStack-Ansible Newton series timeline`_
 
-.. _OpenStack-Ansible Newton Documentation: http://docs.openstack.org/developer/openstack-ansible/newton/
+.. _OpenStack-Ansible Newton Documentation: http://docs.openstack.org/openstack-ansible/newton/
 .. _OpenStack-Ansible Newton series timeline: https://launchpad.net/openstack-ansible/newton
 .. _OpenStack-Ansible Newton series release notes: http://docs.openstack.org/releasenotes/openstack-ansible/newton.html
-
-Mitaka: Security-supported (EOL: 2017-04-10)
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-OpenStack-Ansible's Mitaka Series was first released with the 13.0.0 tag on
-1 April 2016.
-
-* `OpenStack-Ansible Mitaka documentation`_
-
-* `OpenStack-Ansible Mitaka series release notes`_
-
-* `OpenStack-Ansible Mitaka series timeline`_
-
-.. _OpenStack-Ansible Mitaka documentation: http://docs.openstack.org/developer/openstack-ansible/mitaka/
-.. _OpenStack-Ansible Mitaka series timeline: https://launchpad.net/openstack-ansible/mitaka
-.. _OpenStack-Ansible Mitaka series release notes: http://docs.openstack.org/releasenotes/openstack-ansible/mitaka.html
-
-Liberty: Security-supported (EOL: 2016-11-17)
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-OpenStack-Ansible's Liberty Series was first released with the 12.0.0 tag
-on 11 September 2015.
-
-* `OpenStack-Ansible Liberty Documentation`_
-
-* `OpenStack-Ansible Liberty Series Release Notes`_
-
-* `OpenStack-Ansible Liberty Series Timeline`_
-
-.. _OpenStack-Ansible Liberty Documentation: http://docs.openstack.org/developer/openstack-ansible/liberty/
-.. _OpenStack-Ansible Liberty Series Release Notes: http://docs.openstack.org/releasenotes/openstack-ansible/liberty.html
-.. _OpenStack-Ansible Liberty Series Timeline: https://launchpad.net/openstack-ansible/liberty

test-requirements.txt

@@ -13,7 +13,6 @@ virtualenv>=13.1.0 # MIT
 
 # this is required for the docs build jobs
 sphinx>=1.6.2 # BSD
-oslosphinx>=4.7.0 # Apache-2.0
 openstackdocstheme>=1.11.0 # Apache-2.0
 doc8 # Apache-2.0
 reno!=2.3.1,>=1.8.0 # Apache-2.0