From 775141586cbb25270c6e22e0d4b81465f7270bb7 Mon Sep 17 00:00:00 2001 From: Jesse Pretorius Date: Tue, 12 Jul 2016 16:55:44 +0100 Subject: [PATCH] Update sphinx configuration This patch updates the sphinx configuration for docs and releasenotes to make it easier to replicate across repositories and to comply with pep8 testing without exceptions. Change-Id: I8381f5e153edbb9dbf22db634728b862ebe4122c --- doc/source/conf.py | 66 +++++++++++++++++++------------------ releasenotes/source/conf.py | 43 ++++++++++++++---------- 2 files changed, 59 insertions(+), 50 deletions(-) diff --git a/doc/source/conf.py b/doc/source/conf.py index f71b9981..d81afc7e 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -1,22 +1,37 @@ #!/usr/bin/env python3 -# Copyright 2016, Rackspace US, Inc. -# + # 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 # -# http://www.apache.org/licenses/LICENSE-2.0 +# 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. +# 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. -# -- General configuration ------------------------------------------------ +# This file is execfile()d with the current directory set to its +# containing dir. +# +# Note that not all possible configuration values are present in this +# autogenerated file. +# +# 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. +# sys.path.insert(0, os.path.abspath('.')) + +# -- General configuration ------------------------------------------------ # If your documentation needs a minimal Sphinx version, state it here. # needs_sphinx = '1.0' @@ -26,17 +41,10 @@ import os # ones. extensions = [] -# The link to the browsable source code (for the left hand menu) -oslosphinx_cgit_link = ( - 'http://git.openstack.org/cgit/openstack/openstack-ansible-security' -) - # Add any paths that contain templates here, relative to this directory. # templates_path = ['_templates'] # The suffix(es) of source filenames. -# You can specify multiple suffix as a list of string: -# source_suffix = ['.rst', '.md'] source_suffix = '.rst' # The encoding of source files. @@ -46,23 +54,25 @@ source_suffix = '.rst' master_doc = 'index' # General information about the project. -author = 'Openstack-Ansible Contributors' +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' -target_name = 'openstack-ansible-security' -title = "openstack-ansible-security Documentation" +copyright = '2014-2016, OpenStack-Ansible Contributors' +description = 'OpenStack-Ansible deploys OpenStack environments using Ansible.' +project = 'OpenStack-Ansible' +role_name = 'security' +target_name = 'openstack-ansible-' + role_name +title = 'OpenStack-Ansible Documentation: ' + role_name + 'role' # 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. @@ -70,8 +80,7 @@ release = 'master' # 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) +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" @@ -124,10 +133,6 @@ 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 @@ -161,7 +166,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 = ['_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 @@ -210,7 +215,7 @@ html_show_sourcelink = False # html_file_suffix = None # Output file base name for HTML help builder. -htmlhelp_basename = "{0}-docs".format(target_name) +htmlhelp_basename = target_name + '-docs' # If true, publish source files html_copy_source = False @@ -226,9 +231,6 @@ 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 diff --git a/releasenotes/source/conf.py b/releasenotes/source/conf.py index 4c9e12c8..58d4a5b7 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. -# PROJECT_NAME 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,24 @@ source_suffix = '.rst' master_doc = 'index' # General information about the project. -project = u'OpenStack-Ansible Release Notes' -copyright = u'2015, OpenStack-Ansible Developers' +author = 'OpenStack-Ansible Contributors' +category = 'Miscellaneous' +copyright = '2014-2016, OpenStack-Ansible Contributors' +description = 'OpenStack-Ansible deploys OpenStack environments using Ansible.' +project = 'OpenStack-Ansible' +role_name = 'security' +target_name = 'openstack-ansible-' + role_name +title = 'OpenStack-Ansible Release Notes: ' + role_name + 'role' + +# 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-security') +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 +159,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 +199,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 +219,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 +249,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 +263,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.