Browse Source

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: I428a78d781a35e43d53bbcdaeb94658b5e0c91a7
tags/14.0.0.0b2
Jesse Pretorius 2 years ago
parent
commit
7abca60268
2 changed files with 63 additions and 41 deletions
  1. 38
    23
      doc/source/conf.py
  2. 25
    18
      releasenotes/source/conf.py

+ 38
- 23
doc/source/conf.py View File

@@ -1,9 +1,18 @@
1 1
 #!/usr/bin/env python3
2
-# -*- coding: utf-8 -*-
2
+
3
+# Licensed under the Apache License, Version 2.0 (the "License");
4
+# you may not use this file except in compliance with the License.
5
+# You may obtain a copy of the License at
3 6
 #
4
-# openstack-ansible-memcached_server documentation build configuration file, created by
5
-# sphinx-quickstart on Mon Apr 13 20:42:26 2015.
7
+#    http://www.apache.org/licenses/LICENSE-2.0
6 8
 #
9
+# Unless required by applicable law or agreed to in writing, software
10
+# distributed under the License is distributed on an "AS IS" BASIS,
11
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
12
+# implied.
13
+# See the License for the specific language governing permissions and
14
+# limitations under the License.
15
+
7 16
 # This file is execfile()d with the current directory set to its
8 17
 # containing dir.
9 18
 #
@@ -13,6 +22,8 @@
13 22
 # All configuration values have a default; values that are commented out
14 23
 # serve to show the default.
15 24
 
25
+import pbr.version
26
+
16 27
 # If extensions (or modules to document with autodoc) are in another directory,
17 28
 # add these directories to sys.path here. If the directory is relative to the
18 29
 # documentation root, use os.path.abspath to make it absolute, like shown here.
@@ -31,9 +42,6 @@ extensions = [
31 42
     'oslosphinx'
32 43
 ]
33 44
 
34
-# The link to the browsable source code (for the left hand menu)
35
-oslosphinx_cgit_link = 'http://git.openstack.org/cgit/openstack/openstack-ansible-memcached_server'
36
-
37 45
 # Add any paths that contain templates here, relative to this directory.
38 46
 templates_path = ['_templates']
39 47
 
@@ -49,18 +57,28 @@ source_suffix = '.rst'
49 57
 master_doc = 'index'
50 58
 
51 59
 # General information about the project.
52
-project = 'openstack-ansible-memcached_server'
53
-copyright = '2015, openstack-ansible-memcached_server contributors'
54
-author = 'openstack-ansible-memcached_server contributors'
60
+author = 'OpenStack-Ansible Contributors'
61
+category = 'Miscellaneous'
62
+copyright = '2014-2016, OpenStack-Ansible Contributors'
63
+description = 'OpenStack-Ansible deploys OpenStack environments using Ansible.'
64
+project = 'OpenStack-Ansible'
65
+role_name = 'memcached_server'
66
+target_name = 'openstack-ansible-' + role_name
67
+title = 'OpenStack-Ansible Documentation: ' + role_name + 'role'
68
+
69
+# The link to the browsable source code (for the left hand menu)
70
+oslosphinx_cgit_link = 'http://git.openstack.org/cgit/openstack/' + target_name
55 71
 
56 72
 # The version info for the project you're documenting, acts as replacement for
57 73
 # |version| and |release|, also used in various other places throughout the
58 74
 # built documents.
59 75
 #
60 76
 # The short X.Y version.
61
-version = 'master'
77
+version_info = pbr.version.VersionInfo(target_name)
62 78
 # The full version, including alpha/beta/rc tags.
63
-release = 'master'
79
+release = version_info.version_string_with_vcs()
80
+# The short X.Y version.
81
+version = version_info.canonical_version_string()
64 82
 
65 83
 # The language for content autogenerated by Sphinx. Refer to documentation
66 84
 # for a list of supported languages.
@@ -149,7 +167,7 @@ html_static_path = ['_static']
149 167
 
150 168
 # If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
151 169
 # using the given strftime format.
152
-# html_last_updated_fmt = '%b %d, %Y'
170
+html_last_updated_fmt = '%Y-%m-%d %H:%M'
153 171
 
154 172
 # If true, SmartyPants will be used to convert quotes and dashes to
155 173
 # typographically correct entities.
@@ -203,7 +221,7 @@ html_static_path = ['_static']
203 221
 # html_search_scorer = 'scorer.js'
204 222
 
205 223
 # Output file base name for HTML help builder.
206
-htmlhelp_basename = 'openstack-ansible-memcached_serverdoc'
224
+htmlhelp_basename = target_name + '-docs'
207 225
 
208 226
 # -- Options for LaTeX output ---------------------------------------------
209 227
 
@@ -225,9 +243,8 @@ latex_elements = {
225 243
 # (source start file, target name, title,
226 244
 #  author, documentclass [howto, manual, or own class]).
227 245
 latex_documents = [
228
-    (master_doc, 'openstack-ansible-memcached_server.tex',
229
-     'openstack-ansible-memcached_server Documentation',
230
-     'openstack-ansible-memcached_server contributors', 'manual'),
246
+    (master_doc, target_name + '.tex',
247
+     title, author, 'manual'),
231 248
 ]
232 249
 
233 250
 # The name of an image file (relative to this directory) to place at the top of
@@ -256,9 +273,8 @@ latex_documents = [
256 273
 # One entry per manual page. List of tuples
257 274
 # (source start file, name, description, authors, manual section).
258 275
 man_pages = [
259
-    (master_doc, 'openstack-ansible-memcached_server',
260
-     'openstack-ansible-memcached_server Documentation',
261
-     [author], 1)
276
+    (master_doc, target_name,
277
+     title, [author], 1)
262 278
 ]
263 279
 
264 280
 # If true, show URL addresses after external links.
@@ -271,10 +287,9 @@ man_pages = [
271 287
 # (source start file, target name, title, author,
272 288
 #  dir menu entry, description, category)
273 289
 texinfo_documents = [
274
-    (master_doc, 'openstack-ansible-memcached_server',
275
-     'openstack-ansible-memcached_server Documentation',
276
-     author, 'openstack-ansible-memcached_server', 'One line description of project.',
277
-     'Miscellaneous'),
290
+    (master_doc, target_name,
291
+     title, author, project,
292
+     description, category),
278 293
 ]
279 294
 
280 295
 # Documents to append as an appendix to all manuals.

+ 25
- 18
releasenotes/source/conf.py View File

@@ -1,4 +1,5 @@
1
-# -*- coding: utf-8 -*-
1
+#!/usr/bin/env python3
2
+
2 3
 # Licensed under the Apache License, Version 2.0 (the "License");
3 4
 # you may not use this file except in compliance with the License.
4 5
 # You may obtain a copy of the License at
@@ -12,9 +13,6 @@
12 13
 # See the License for the specific language governing permissions and
13 14
 # limitations under the License.
14 15
 
15
-# PROJECT_NAME Release Notes documentation build configuration file, created by
16
-# sphinx-quickstart on Tue Nov  3 17:40:50 2015.
17
-#
18 16
 # This file is execfile()d with the current directory set to its
19 17
 # containing dir.
20 18
 #
@@ -24,6 +22,8 @@
24 22
 # All configuration values have a default; values that are commented out
25 23
 # serve to show the default.
26 24
 
25
+import pbr.version
26
+
27 27
 # If extensions (or modules to document with autodoc) are in another directory,
28 28
 # add these directories to sys.path here. If the directory is relative to the
29 29
 # documentation root, use os.path.abspath to make it absolute, like shown here.
@@ -55,16 +55,24 @@ source_suffix = '.rst'
55 55
 master_doc = 'index'
56 56
 
57 57
 # General information about the project.
58
-project = u'OpenStack-Ansible Release Notes'
59
-copyright = u'2015, OpenStack-Ansible Developers'
58
+author = 'OpenStack-Ansible Contributors'
59
+category = 'Miscellaneous'
60
+copyright = '2014-2016, OpenStack-Ansible Contributors'
61
+description = 'OpenStack-Ansible deploys OpenStack environments using Ansible.'
62
+project = 'OpenStack-Ansible'
63
+role_name = 'memcached_server'
64
+target_name = 'openstack-ansible-' + role_name
65
+title = 'OpenStack-Ansible Release Notes: ' + role_name + 'role'
66
+
67
+# The link to the browsable source code (for the left hand menu)
68
+oslosphinx_cgit_link = 'http://git.openstack.org/cgit/openstack/' + target_name
60 69
 
61 70
 # The version info for the project you're documenting, acts as replacement for
62 71
 # |version| and |release|, also used in various other places throughout the
63 72
 # built documents.
64 73
 #
65 74
 # The short X.Y version.
66
-import pbr.version
67
-version_info = pbr.version.VersionInfo('openstack-ansible-memcached_server')
75
+version_info = pbr.version.VersionInfo(target_name)
68 76
 # The full version, including alpha/beta/rc tags.
69 77
 release = version_info.version_string_with_vcs()
70 78
 # The short X.Y version.
@@ -151,7 +159,7 @@ html_static_path = ['_static']
151 159
 
152 160
 # If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
153 161
 # using the given strftime format.
154
-# html_last_updated_fmt = '%b %d, %Y'
162
+html_last_updated_fmt = '%Y-%m-%d %H:%M'
155 163
 
156 164
 # If true, SmartyPants will be used to convert quotes and dashes to
157 165
 # typographically correct entities.
@@ -191,7 +199,7 @@ html_static_path = ['_static']
191 199
 # html_file_suffix = None
192 200
 
193 201
 # Output file base name for HTML help builder.
194
-htmlhelp_basename = 'OpenStackAnsibleReleaseNotesdoc'
202
+htmlhelp_basename = target_name + '-docs'
195 203
 
196 204
 
197 205
 # -- Options for LaTeX output ---------------------------------------------
@@ -211,8 +219,8 @@ latex_elements = {
211 219
 # (source start file, target name, title,
212 220
 #  author, documentclass [howto, manual, or own class]).
213 221
 latex_documents = [
214
-    ('index', 'OpenStackAnsibleReleaseNotes.tex', u'OpenStack-Ansible Release Notes Documentation',
215
-     u'OpenStack-Ansible Developers', 'manual'),
222
+    (master_doc, target_name + '.tex',
223
+     title, author, 'manual'),
216 224
 ]
217 225
 
218 226
 # The name of an image file (relative to this directory) to place at the top of
@@ -241,8 +249,8 @@ latex_documents = [
241 249
 # One entry per manual page. List of tuples
242 250
 # (source start file, name, description, authors, manual section).
243 251
 man_pages = [
244
-    ('index', 'openstackansiblereleasenotes', u'OpenStack-Ansible Release Notes Documentation',
245
-     [u'OpenStack-Ansible Developers'], 1)
252
+    (master_doc, target_name,
253
+     title, [author], 1)
246 254
 ]
247 255
 
248 256
 # If true, show URL addresses after external links.
@@ -255,10 +263,9 @@ man_pages = [
255 263
 # (source start file, target name, title, author,
256 264
 #  dir menu entry, description, category)
257 265
 texinfo_documents = [
258
-    ('index', 'OpenStackAnsibleReleaseNotes', u'OpenStack-Ansible Release Notes Documentation',
259
-     u'OpenStack-Ansible Developers', 'OpenStackAnsibleReleaseNotes',
260
-     'One line description of project.',
261
-     'Miscellaneous'),
266
+    (master_doc, target_name,
267
+     title, author, project,
268
+     description, category),
262 269
 ]
263 270
 
264 271
 # Documents to append as an appendix to all manuals.

Loading…
Cancel
Save