From 03041378f2291ce84e435076df4bde57a8c84ece Mon Sep 17 00:00:00 2001 From: Jesse Pretorius Date: Wed, 6 Jul 2016 15:01:20 +0100 Subject: [PATCH] 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 --- doc/source/conf.py | 129 +++++++++++++++-------------- doc/source/index.rst | 21 +++-- doc/source/install-guide/index.rst | 3 +- releasenotes/source/conf.py | 42 ++++++---- test-requirements.txt | 2 + tox.ini | 9 ++ 6 files changed, 118 insertions(+), 88 deletions(-) diff --git a/doc/source/conf.py b/doc/source/conf.py index 0844b38dfa..806573e000 100644 --- 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 # " v 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) +] diff --git a/doc/source/index.rst b/doc/source/index.rst index 1fccae0d62..f71f4bab1b 100644 --- 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. diff --git a/doc/source/install-guide/index.rst b/doc/source/install-guide/index.rst index 1c47bc2c3a..5705d909fc 100644 --- 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 \ No newline at end of file + app-custom-layouts.rst + diff --git a/releasenotes/source/conf.py b/releasenotes/source/conf.py index 7a8ccc569b..3bc652b2a1 100644 --- 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. diff --git a/test-requirements.txt b/test-requirements.txt index b8a3f5a71f..8c9f8207b1 100644 --- 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 diff --git a/tox.ini b/tox.ini index 1e818063c2..dbbc9790bb 100644 --- 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