From ad97caea6372555adda0a96c373e0c9a2634e402 Mon Sep 17 00:00:00 2001 From: Jesse Pretorius Date: Tue, 12 Jul 2016 16:53:12 +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: I2b46927a22150d2a0d21fdec73eb404114cbdb7e --- doc/source/conf.py | 61 +++++++++++++++++++++++-------------- releasenotes/source/conf.py | 43 +++++++++++++++----------- 2 files changed, 63 insertions(+), 41 deletions(-) diff --git a/doc/source/conf.py b/doc/source/conf.py index 4a758f20..13a2ee0c 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-ironic 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,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. @@ -31,9 +42,6 @@ extensions = [ 'oslosphinx' ] -# The link to the browsable source code (for the left hand menu) -oslosphinx_cgit_link = 'http://git.openstack.org/cgit/openstack/openstack-ansible-ironic' - # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] @@ -49,18 +57,28 @@ source_suffix = '.rst' master_doc = 'index' # General information about the project. -project = 'openstack-ansible-ironic' -copyright = '2015, openstack-ansible-ironic contributors' -author = 'openstack-ansible-ironic contributors' +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 = 'os_ironic' +target_name = 'openstack-ansible-' + role_name +title = 'OpenStack-Ansible Documentation: ' + 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. -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() # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. @@ -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. @@ -203,7 +221,7 @@ html_static_path = ['_static'] # html_search_scorer = 'scorer.js' # Output file base name for HTML help builder. -htmlhelp_basename = 'openstack-ansible-ironicdoc' +htmlhelp_basename = target_name + '-docs' # -- Options for LaTeX output --------------------------------------------- @@ -225,9 +243,8 @@ latex_elements = { # (source start file, target name, title, # author, documentclass [howto, manual, or own class]). latex_documents = [ - (master_doc, 'openstack-ansible-ironic.tex', - 'openstack-ansible-ironic Documentation', - 'openstack-ansible-ironic 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 +273,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-ironic', - 'openstack-ansible-ironic Documentation', - [author], 1) + (master_doc, target_name, + title, [author], 1) ] # If true, show URL addresses after external links. @@ -271,10 +287,9 @@ man_pages = [ # (source start file, target name, title, author, # dir menu entry, description, category) texinfo_documents = [ - (master_doc, 'openstack-ansible-ironic', - 'openstack-ansible-ironic Documentation', - author, 'openstack-ansible-ironic', '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/releasenotes/source/conf.py b/releasenotes/source/conf.py index 04caceab..4093aab2 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 = 'os_ironic' +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-ironic') +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.