Docs: Implement Manuals Theme and doc8 checks

This patch implements: - The OpenStack Manuals documentation theme. - Some minor content changes to the index pages to ensure that they render correctly. - Adjustments to the tox/requirements configuration in order to implement doc8 checks to facilitate improved documentation checking for incoming patches. - Adjustments to the sphinx configuration for easier maintenance. Note: The bug_title in the openstackdocstheme is not currently customisable. A patch to implement the ability to do so has been submitted: https://review.openstack.org/338299 Partially-Implements: blueprint osa-install-guide-overhaul Change-Id: I8af1a7ce9008e70abad00be96614c9997f59596b
2016-07-06 15:01:20 +01:00 · 2016-07-06 15:01:20 +01:00 · 03041378f2
commit 03041378f2
parent 89d82b00fd
6 changed files with 118 additions and 88 deletions
--- a/doc/source/conf.py
+++ b/doc/source/conf.py
@ -1,9 +1,18 @@
 #!/usr/bin/env python3
-# -*- coding: utf-8 -*-
+
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
 #
-# OpenStack-Ansible Documentation build configuration file, created by
-# sphinx-quickstart on Mon Apr 13 20:42:26 2015.
+#    http://www.apache.org/licenses/LICENSE-2.0
 #
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+# implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
 # This file is execfile()d with the current directory set to its
 # containing dir.
 #
@ -13,6 +22,10 @@
 # All configuration values have a default; values that are commented out
 # serve to show the default.

+import openstackdocstheme
+import os
+import pbr.version
+
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
@ -26,20 +39,13 @@
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = [
-    'sphinx.ext.autodoc',
-    'oslosphinx'
-]
-
-# The link to the browsable source code (for the left hand menu)
-oslosphinx_cgit_link = 'http://git.openstack.org/cgit/openstack/openstack-ansible'
+# TODO(ajaeger): enable PDF building, for example add 'rst2pdf.pdfbuilder'
+extensions = []

 # Add any paths that contain templates here, relative to this directory.
-templates_path = ['_templates']
+#templates_path = ['_templates']

-# The suffix(es) of source filenames.
-# You can specify multiple suffix as a list of string:
-# source_suffix = ['.rst', '.md']
+# The suffix of source filenames.
 source_suffix = '.rst'

 # The encoding of source files.
@ -49,25 +55,41 @@ source_suffix = '.rst'
 master_doc = 'index'

 # General information about the project.
-project = 'OpenStack-Ansible'
-copyright = '2016, OpenStack-Ansible Contributors'
 author = 'OpenStack-Ansible Contributors'
+category = 'Miscellaneous'
+copyright = '2014-2016, OpenStack-Ansible Contributors'
+description = 'OpenStack-Ansible deploys OpenStack environments using Ansible.'
+project = 'OpenStack-Ansible'
+target_name = 'openstack-ansible'
+title = 'OpenStack-Ansible Documentation'

 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
 # built documents.
 #
 # The short X.Y version.
-version = 'master'
+version_info = pbr.version.VersionInfo(target_name)
 # The full version, including alpha/beta/rc tags.
-release = 'master'
+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 = 'http://git.openstack.org/cgit/openstack/' + target_name + '/tree/doc/source'
+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}

 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
-#
-# This is also used if you do content translation via gettext catalogs.
-# Usually you set "language" from the command line for these cases.
-language = None
+# language = None

 # There are two options for replacing |today|: either, you set today to some
 # non-false value, then it is used:
@ -103,15 +125,11 @@ 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
 # a list of builtin themes.
-# html_theme = 'alabaster'
+html_theme = 'openstackdocs'

 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
@ -119,7 +137,7 @@ todo_include_todos = False
 # html_theme_options = {}

 # Add any paths that contain custom themes here, relative to this directory.
-# html_theme_path = []
+html_theme_path = [openstackdocstheme.get_html_theme_path()]

 # The name for this set of Sphinx documents.  If None, it defaults to
 # "<project> v<release> documentation".
@ -140,7 +158,7 @@ todo_include_todos = False
 # 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 = []

 # Add any extra paths that contain custom files (such as robots.txt or
 # .htaccess) here, relative to this directory. These files are copied
@ -149,7 +167,7 @@ html_static_path = ['_static']

 # If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
 # using the given strftime format.
-# html_last_updated_fmt = '%b %d, %Y'
+html_last_updated_fmt = '%Y-%m-%d %H:%M'

 # If true, SmartyPants will be used to convert quotes and dashes to
 # typographically correct entities.
@ -166,13 +184,13 @@ html_static_path = ['_static']
 # html_domain_indices = True

 # If false, no index is generated.
-# html_use_index = True
+html_use_index = False

 # 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 = True
+html_show_sourcelink = False

 # If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
 # html_show_sphinx = True
@ -188,22 +206,11 @@ html_static_path = ['_static']
 # This is the file name suffix for HTML files (e.g. ".xhtml").
 # html_file_suffix = None

-# Language to be used for generating the HTML full-text search index.
-# Sphinx supports the following languages:
-#   'da', 'de', 'en', 'es', 'fi', 'fr', 'h', 'it', 'ja'
-#   'nl', 'no', 'pt', 'ro', 'r', 'sv', 'tr'
-# html_search_language = 'en'
-
-# A dictionary with options for the search language support, empty by default.
-# Now only 'ja' uses this config value
-# html_search_options = {'type': 'default'}
-
-# The name of a javascript file (relative to the configuration directory) that
-# implements a search results scorer. If empty, the default will be used.
-# html_search_scorer = 'scorer.js'
-
 # Output file base name for HTML help builder.
-htmlhelp_basename = 'openstack-ansibledoc'
+htmlhelp_basename = target_name + '-docs'
+
+# If true, publish source files
+html_copy_source = False

 # -- Options for LaTeX output ---------------------------------------------

@ -216,18 +223,14 @@ latex_elements = {

    # Additional stuff for the LaTeX preamble.
    # 'preamble': '',
-
-    # Latex figure (float) alignment
-    # 'figure_align': 'htbp',
 }

 # Grouping the document tree into LaTeX files. List of tuples
 # (source start file, target name, title,
 #  author, documentclass [howto, manual, or own class]).
 latex_documents = [
-    (master_doc, 'openstack-ansible.tex',
-     'OpenStack-Ansible Documentation',
-     'OpenStack-Ansible Contributors', 'manual'),
+    (master_doc, target_name + '.tex',
+     title, author, 'manual'),
 ]

 # The name of an image file (relative to this directory) to place at the top of
@ -256,9 +259,8 @@ latex_documents = [
 # One entry per manual page. List of tuples
 # (source start file, name, description, authors, manual section).
 man_pages = [
-    (master_doc, 'openstack-ansible',
-     'OpenStack-Ansible Documentation',
-     [author], 1)
+    (master_doc, target_name,
+     title, [author], 1)
 ]

 # If true, show URL addresses after external links.
@ -271,11 +273,9 @@ man_pages = [
 # (source start file, target name, title, author,
 #  dir menu entry, description, category)
 texinfo_documents = [
-    (master_doc, 'openstack-ansible',
-     'OpenStack-Ansible Documentation',
-     author, 'OpenStack-Ansible',
-     'OpenStack-Ansible deploys OpenStack environments using Ansible.',
-     'Miscellaneous'),
+    (master_doc, target_name,
+     title, author, project,
+     description, category),
 ]

 # Documents to append as an appendix to all manuals.
@ -289,3 +289,10 @@ texinfo_documents = [

 # If true, do not generate a @detailmenu in the "Top" node's menu.
 # texinfo_no_detailmenu = False
+
+# -- Options for PDF output --------------------------------------------------
+
+pdf_documents = [
+    (master_doc, target_name,
+     title, author)
+]
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@ -1,11 +1,16 @@
-Welcome to OpenStack-Ansible's documentation!
-=============================================
+===============================
+OpenStack-Ansible Documentation
+===============================

-This project provides Ansible playbooks and roles for the deployment and
+Abstract
+~~~~~~~~
+OpenStack-Ansible provides Ansible playbooks and roles for the deployment and
 configuration of an OpenStack environment.

+Documentation for each of the following releases is available.
+
 Newton (unreleased)
-===================
+~~~~~~~~~~~~~~~~~~~

 OpenStack-Ansible Newton is currently in development. The
 `Newton Series Timeline`_ and `Newton Series Release Notes`_ are available for
@ -27,7 +32,7 @@ review.
 .. _Newton Series Release Notes: http://docs.openstack.org/releasenotes/openstack-ansible/unreleased.html

 Mitaka (Current stable release, security-supported)
-===================================================
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

 OpenStack-Ansible's Mitaka Series was first released with the 13.0.0 tag on
 1 April 2016.
@ -43,7 +48,7 @@ OpenStack-Ansible's Mitaka Series was first released with the 13.0.0 tag on
 .. _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.
@ -58,8 +63,8 @@ on 11 September 2015.
 .. _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

-Kilo: Security-supported (EOL: 2016-05-02)
-==========================================
+Kilo: End of Life (2016-07-05)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

 OpenStack-Ansible's Kilo series was first released with the 11.0.0 tag on
 30 April 2015.
--- a/doc/source/install-guide/index.rst
+++ b/doc/source/install-guide/index.rst
@ -52,4 +52,5 @@ Appendices
   app-resources.rst
   app-plumgrid.rst
   app-nuage.rst
-   app-custom-layouts.rst
+   app-custom-layouts.rst
+
--- a/releasenotes/source/conf.py
+++ b/releasenotes/source/conf.py
@ -1,4 +1,5 @@
-# -*- coding: utf-8 -*-
+#!/usr/bin/env python3
+
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
 # You may obtain a copy of the License at
@ -12,9 +13,6 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.

-# Glance Release Notes documentation build configuration file, created by
-# sphinx-quickstart on Tue Nov  3 17:40:50 2015.
-#
 # This file is execfile()d with the current directory set to its
 # containing dir.
 #
@ -24,6 +22,8 @@
 # All configuration values have a default; values that are commented out
 # serve to show the default.

+import pbr.version
+
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
@ -55,16 +55,23 @@ source_suffix = '.rst'
 master_doc = 'index'

 # General information about the project.
-project = u'OpenStack-Ansible Release Notes'
-copyright = u'2015, OpenStack-Ansible Developers'
+author = u'OpenStack-Ansible Contributors'
+category = u'Miscellaneous'
+copyright = u'2014-2016, OpenStack-Ansible Contributors'
+description = u'OpenStack-Ansible deploys OpenStack environments using Ansible.'
+project = u'OpenStack-Ansible'
+target_name = u'openstack-ansible'
+title = u'OpenStack-Ansible Release Notes'
+
+# The link to the browsable source code (for the left hand menu)
+oslosphinx_cgit_link = 'http://git.openstack.org/cgit/openstack/' + target_name

 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
 # built documents.
 #
 # The short X.Y version.
-import pbr.version
-version_info = pbr.version.VersionInfo('openstack-ansible')
+version_info = pbr.version.VersionInfo(target_name)
 # The full version, including alpha/beta/rc tags.
 release = version_info.version_string_with_vcs()
 # The short X.Y version.
@ -151,7 +158,7 @@ html_static_path = ['_static']

 # If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
 # using the given strftime format.
-# html_last_updated_fmt = '%b %d, %Y'
+html_last_updated_fmt = '%Y-%m-%d %H:%M'

 # If true, SmartyPants will be used to convert quotes and dashes to
 # typographically correct entities.
@ -191,7 +198,7 @@ html_static_path = ['_static']
 # html_file_suffix = None

 # Output file base name for HTML help builder.
-htmlhelp_basename = 'OpenStackAnsibleReleaseNotesdoc'
+htmlhelp_basename = target_name + '-docs'


 # -- Options for LaTeX output ---------------------------------------------
@ -211,8 +218,8 @@ latex_elements = {
 # (source start file, target name, title,
 #  author, documentclass [howto, manual, or own class]).
 latex_documents = [
-    ('index', 'OpenStackAnsibleReleaseNotes.tex', u'OpenStack-Ansible Release Notes Documentation',
-     u'OpenStack-Ansible Developers', 'manual'),
+    (master_doc, target_name + '.tex',
+     title, author, 'manual'),
 ]

 # The name of an image file (relative to this directory) to place at the top of
@ -241,8 +248,8 @@ latex_documents = [
 # One entry per manual page. List of tuples
 # (source start file, name, description, authors, manual section).
 man_pages = [
-    ('index', 'openstackansiblereleasenotes', u'OpenStack-Ansible Release Notes Documentation',
-     [u'OpenStack-Ansible Developers'], 1)
+    (master_doc, target_name,
+     title, [author], 1)
 ]

 # If true, show URL addresses after external links.
@ -255,10 +262,9 @@ man_pages = [
 # (source start file, target name, title, author,
 #  dir menu entry, description, category)
 texinfo_documents = [
-    ('index', 'OpenStackAnsibleReleaseNotes', u'OpenStack-Ansible Release Notes Documentation',
-     u'OpenStack-Ansible Developers', 'OpenStackAnsibleReleaseNotes',
-     'One line description of project.',
-     'Miscellaneous'),
+    (master_doc, target_name,
+     title, author, project,
+     description, category),
 ]

 # Documents to append as an appendix to all manuals.
--- a/test-requirements.txt
+++ b/test-requirements.txt
@ -11,4 +11,6 @@ virtualenv>=14.0.0
 # this is required for the docs build jobs
 sphinx!=1.2.0,!=1.3b1,<1.3,>=1.1.2
 oslosphinx>=2.5.0 # Apache-2.0
+openstackdocstheme>=1.2.3
+doc8 # Apache-2.0
 reno>=0.1.1 # Apache-2.0
--- a/tox.ini
+++ b/tox.ini
@ -30,9 +30,18 @@ setenv =
 [testenv:docs]
 commands=
    bash -c "rm -rf doc/build"
+    doc8 doc
    python setup.py build_sphinx


+[doc8]
+# Settings for doc8:
+extensions = .rst
+# Disable some doc8 checks:
+# D000: Check RST validity
+# D001 Line too long
+ignore = D000,D001
+
 [testenv:releasenotes]
 # NOTE(sdague): this target does not use constraints because
 # upstream infra does not yet support it. Once that's fixed, we can