Switch to openstackdocs theme

This patch updates the docs for the security role to use the
openstackdocs theme and adds doc8 linting. This matches up with
OpenStack-Ansible's docs changes.

Change-Id: Ie8265bdaf8f8b91454766f5beba14645aabf77cc

doc/source/conf.py

@@ -15,16 +15,16 @@
 
 # -- General configuration ------------------------------------------------
 
+import openstackdocstheme
+import os
+
 # If your documentation needs a minimal Sphinx version, state it here.
 # needs_sphinx = '1.0'
 
 # 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'
-]
+extensions = []
 
 # The link to the browsable source code (for the left hand menu)
 oslosphinx_cgit_link = (
@@ -32,7 +32,7 @@ oslosphinx_cgit_link = (
 )
 
 # 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:
@@ -46,9 +46,14 @@ source_suffix = '.rst'
 master_doc = 'index'
 
 # General information about the project.
+author = 'Openstack-Ansible Contributors'
+category = 'Miscellaneous'
+copyright = '2015-2016, OpenStack-Ansible contributors'
+description = ("openstack-ansible-security applies security hardening to"
+               "OpenStack hosts.")
 project = 'openstack-ansible-security'
-copyright = '2015, openstack-ansible contributors'
-author = 'openstack-ansible contributors'
+target_name = 'openstack-ansible-security'
+title = "openstack-ansible-security 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
@@ -59,6 +64,22 @@ version = 'master'
 # The full version, including alpha/beta/rc tags.
 release = 'master'
 
+# 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/{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}
+
+
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
 #
@@ -111,7 +132,7 @@ todo_include_todos = False
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
-html_theme = 'openstack'
+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 +140,7 @@ html_theme = 'openstack'
 # html_theme_options = {}
 
 # Add any paths that contain custom themes here, relative to this directory.
-html_theme_path = ['_themes']
+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 +161,7 @@ html_theme_path = ['_themes']
 # 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
@@ -149,7 +170,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 +187,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 +209,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 = "{0}-docs".format(target_name)
+
+# If true, publish source files
+html_copy_source = False
 
 # -- Options for LaTeX output ---------------------------------------------
 
@@ -225,9 +235,8 @@ latex_elements = {
 # (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 +265,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,10 +279,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', 'One line description of project.',
-     'Miscellaneous'),
+    (master_doc, target_name,
+     title, author, project,
+     description, category),
 ]
 
 # Documents to append as an appendix to all manuals.
@@ -288,3 +295,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)
+]

doc/source/developer-notes/V-38459.rst

@@ -1 +1 @@
-The tasks in file_perms.yml will ensure that "/etc/group" is owned by the root account.
+The tasks in file_perms.yml will ensure that "/etc/group" is owned by the root account.

doc/source/developer-notes/V-38677.rst

@@ -1,2 +1,2 @@
 The tasks in nfsd.yml first check to see if the system has nfs exports. If
-so, it then checks for the presence of 'insecure_locks'.
+so, it then checks for the presence of 'insecure_locks'.

doc/source/index.rst

@@ -1,5 +1,9 @@
-Security hardening for openstack-ansible
 ========================================
+Security hardening for OpenStack-Ansible
+========================================
+
+Abstract
+~~~~~~~~
 
 The openstack-ansible-security role provides security hardening for `OpenStack`_
 environments deployed with `openstack-ansible`_.  The role has multiple goals:
@@ -25,7 +29,7 @@ metadata is through the `STIG Viewer`_ service provided by `UCF`_.
 .. _UCF: http://www.unifiedcompliance.com/
 
 Newton: Development
-===================
+~~~~~~~~~~~~~~~~~~~
 
 The openstack-ansible-security role is currently under development for the
 Newton release. The Newton release supports the following Linux distributions:
@@ -45,7 +49,7 @@ Newton release. The Newton release supports the following Linux distributions:
    developer-guide.rst
 
 Mitaka: Stable release
-===================================================
+~~~~~~~~~~~~~~~~~~~~~~
 
 The Mitaka release of the openstack-ansible-security role was first released
 with the 13.0.0 tag on April 1st, 2016.  Refer to the `Mitaka release notes
@@ -59,7 +63,7 @@ Ubuntu 14.04 is supported in the Mitaka release.
 .. _openstack-ansible-security Mitaka Documentation: http://docs.openstack.org/developer/openstack-ansible-security/mitaka/
 
 Liberty: Previous stable release (EOL: 2016-11-17)
-==================================================
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Refer to the `Liberty release notes
 <http://docs.openstack.org/releasenotes/openstack-ansible-security/liberty.html>`_

test-requirements.txt

@@ -6,4 +6,6 @@ flake8>=2.5.4,<2.6.0  # MIT
 # this is required for the docs build jobs
 sphinx>=1.1.2,!=1.2.0,!=1.3b1,<1.3  # BSD
 oslosphinx>=2.5.0,!=3.4.0  # Apache-2.0
+openstackdocstheme>=1.2.3
+doc8 # Apache-2.0
 reno>=1.6.2 # Apache-2.0

tox.ini

@@ -37,9 +37,21 @@ 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
+# D002 Trailing whitespace
+ignore = D000,D001,D002
+
+
 # environment used by the -infra templated docs job
 [testenv:venv]
 deps = -r{toxinidir}/test-requirements.txt