← Back to branch summary

~ubuntu-branches/ubuntu/trusty/heat/trusty

« back to all changes in this revision

Viewing changes to doc/source/conf.py

  • Committer: Package Import Robot
  • Author(s): Chuck Short, Chuck Short, Adam Gandelman
  • Date: 2013-09-08 21:51:19 UTC
  • mfrom: (1.1.4)
  • Revision ID: package-import@ubuntu.com-20130908215119-r939tu4aumqgdrkx
Tags: 2013.2~b3-0ubuntu1
[ Chuck Short ]
* New upstream release.
* debian/control: Add python-netaddr as build-dep.
* debian/heat-common.install: Remove heat-boto and associated man-page
* debian/heat-common.install: Remove heat-cfn and associated man-page
* debian/heat-common.install: Remove heat-watch and associated man-page
* debian/patches/fix-sqlalchemy-0.8.patch: Dropped

[ Adam Gandelman ]
* debian/patches/default-kombu.patch: Dropped.
* debian/patches/default-sqlite.patch: Refreshed.
* debian/*.install, rules: Install heat.conf.sample as common
  config file in heat-common. Drop other per-package configs, they
  are no longer used.
* debian/rules: Clean pbr .egg from build dir if it exists.

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/source/conf.py
1
1
# -*- coding: utf-8 -*-
2
2
#
 
3
#    Licensed under the Apache License, Version 2.0 (the "License"); you may
 
4
#    not use this file except in compliance with the License. You may obtain
 
5
#    a copy of the License at
 
6
#
 
7
#         http://www.apache.org/licenses/LICENSE-2.0
 
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, WITHOUT
 
11
#    WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
 
12
#    License for the specific language governing permissions and limitations
 
13
#    under the License.
 
14
#
3
15
# Heat documentation build configuration file, created by
4
16
# sphinx-quickstart on Thu Dec 13 11:23:35 2012.
5
17
#
15
27
import os
16
28
import sys
17
29
 
 
30
BASE_DIR = os.path.dirname(os.path.abspath(__file__))
 
31
ROOT = os.path.abspath(os.path.join(BASE_DIR, "..", ".."))
 
32
 
 
33
sys.path.insert(0, ROOT)
 
34
sys.path.insert(0, BASE_DIR)
 
35
 
 
36
# This is required for ReadTheDocs.org, but isn't a bad idea anyway.
 
37
os.environ['DJANGO_SETTINGS_MODULE'] = 'openstack_dashboard.settings'
 
38
 
 
39
 
 
40
def write_autodoc_index():
 
41
 
 
42
    def find_autodoc_modules(module_name, sourcedir):
 
43
        """Return a list of modules in the SOURCE directory."""
 
44
        modlist = []
 
45
        os.chdir(os.path.join(sourcedir, module_name))
 
46
        print "SEARCHING %s" % sourcedir
 
47
        for root, dirs, files in os.walk("."):
 
48
            for filename in files:
 
49
                if filename.endswith(".py"):
 
50
                    # remove the pieces of the root
 
51
                    elements = root.split(os.path.sep)
 
52
                    # replace the leading "." with the module name
 
53
                    elements[0] = module_name
 
54
                    # and get the base module name
 
55
                    base, extension = os.path.splitext(filename)
 
56
                    if not (base == "__init__"):
 
57
                        elements.append(base)
 
58
                    result = ".".join(elements)
 
59
                    #print result
 
60
                    modlist.append(result)
 
61
        return modlist
 
62
 
 
63
    RSTDIR = os.path.abspath(os.path.join(BASE_DIR, "sourcecode"))
 
64
    SRCS = {'heat': ROOT}
 
65
 
 
66
    EXCLUDED_MODULES = ('heat.tests',
 
67
                        'heat.testing',
 
68
                        'heat.cmd',
 
69
                        'heat.common',
 
70
                        'heat.cloudinit',
 
71
                        'heat.cfn_client',
 
72
                        'heat.doc',
 
73
                        'heat.db',
 
74
                        'heat.engine.resources',
 
75
                        'heat.locale',
 
76
                        'heat.openstack')
 
77
    CURRENT_SOURCES = {}
 
78
 
 
79
    if not(os.path.exists(RSTDIR)):
 
80
        os.mkdir(RSTDIR)
 
81
    CURRENT_SOURCES[RSTDIR] = ['autoindex.rst', '.gitignore']
 
82
 
 
83
    INDEXOUT = open(os.path.join(RSTDIR, "autoindex.rst"), "w")
 
84
    INDEXOUT.write("=================\n")
 
85
    INDEXOUT.write("Source Code Index\n")
 
86
    INDEXOUT.write("=================\n")
 
87
 
 
88
    for modulename, path in SRCS.items():
 
89
        sys.stdout.write("Generating source documentation for %s\n" %
 
90
                         modulename)
 
91
        INDEXOUT.write("\n%s\n" % modulename.capitalize())
 
92
        INDEXOUT.write("%s\n" % ("=" * len(modulename),))
 
93
        INDEXOUT.write(".. toctree::\n")
 
94
        INDEXOUT.write("   :maxdepth: 1\n")
 
95
        INDEXOUT.write("\n")
 
96
 
 
97
        MOD_DIR = os.path.join(RSTDIR, modulename)
 
98
        CURRENT_SOURCES[MOD_DIR] = []
 
99
        if not(os.path.exists(MOD_DIR)):
 
100
            os.mkdir(MOD_DIR)
 
101
        for module in find_autodoc_modules(modulename, path):
 
102
            if any([module.startswith(exclude)
 
103
                    for exclude
 
104
                    in EXCLUDED_MODULES]):
 
105
                print "Excluded module %s." % module
 
106
                continue
 
107
            mod_path = os.path.join(path, *module.split("."))
 
108
            generated_file = os.path.join(MOD_DIR, "%s.rst" % module)
 
109
 
 
110
            INDEXOUT.write("   %s/%s\n" % (modulename, module))
 
111
 
 
112
            # Find the __init__.py module if this is a directory
 
113
            if os.path.isdir(mod_path):
 
114
                source_file = ".".join((os.path.join(mod_path, "__init__"),
 
115
                                        "py",))
 
116
            else:
 
117
                source_file = ".".join((os.path.join(mod_path), "py"))
 
118
 
 
119
            CURRENT_SOURCES[MOD_DIR].append("%s.rst" % module)
 
120
            # Only generate a new file if the source has changed or we don't
 
121
            # have a doc file to begin with.
 
122
            if not os.access(generated_file, os.F_OK) or \
 
123
                    os.stat(generated_file).st_mtime < \
 
124
                    os.stat(source_file).st_mtime:
 
125
                print "Module %s updated, generating new documentation." \
 
126
                      % module
 
127
                FILEOUT = open(generated_file, "w")
 
128
                header = "The :mod:`%s` Module" % module
 
129
                FILEOUT.write("%s\n" % ("=" * len(header),))
 
130
                FILEOUT.write("%s\n" % header)
 
131
                FILEOUT.write("%s\n" % ("=" * len(header),))
 
132
                FILEOUT.write(".. automodule:: %s\n" % module)
 
133
                FILEOUT.write("  :members:\n")
 
134
                FILEOUT.write("  :undoc-members:\n")
 
135
                FILEOUT.write("  :show-inheritance:\n")
 
136
                FILEOUT.write("  :noindex:\n")
 
137
                FILEOUT.close()
 
138
 
 
139
    INDEXOUT.close()
 
140
 
 
141
    # Delete auto-generated .rst files for sources which no longer exist
 
142
    for directory, subdirs, files in list(os.walk(RSTDIR)):
 
143
        for old_file in files:
 
144
            if old_file not in CURRENT_SOURCES.get(directory, []):
 
145
                print "Removing outdated file for %s" % old_file
 
146
                os.remove(os.path.join(directory, old_file))
 
147
 
 
148
 
 
149
write_autodoc_index()
 
150
 
18
151
# If extensions (or modules to document with autodoc) are in another directory,
19
152
# add these directories to sys.path here. If the directory is relative to the
20
153
# documentation root, use os.path.abspath to make it absolute, like shown here.
21
 
sys.path.insert(0, os.path.abspath('../../'))
 
154
#sys.path.insert(0, os.path.abspath('.'))
22
155
 
23
156
# -- General configuration ----------------------------------------------------
24
157
 
28
161
# Add any Sphinx extension module names here, as strings. They can be
29
162
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
30
163
extensions = ['sphinx.ext.autodoc',
31
 
    'sphinx.ext.ifconfig',
32
 
    'sphinx.ext.viewcode',
33
 
    'heat.doc.resources']
 
164
              'sphinx.ext.ifconfig',
 
165
              'sphinx.ext.viewcode',
 
166
              'sphinx.ext.todo',
 
167
              'sphinx.ext.coverage',
 
168
              'sphinx.ext.pngmath',
 
169
              'sphinx.ext.viewcode',
 
170
              'oslo.sphinx',
 
171
              'heat.doc.resources']
 
172
 
 
173
todo_include_todos = True
34
174
 
35
175
# Add any paths that contain templates here, relative to this directory.
36
 
#templates_path = ['_templates']
 
176
if os.getenv('HUDSON_PUBLISH_DOCS'):
 
177
    templates_path = ['_ga', '_templates']
 
178
else:
 
179
    templates_path = ['_templates']
37
180
 
38
181
# The suffix of source filenames.
39
182
source_suffix = '.rst'
60
203
 
61
204
# List of patterns, relative to source directory, that match files and
62
205
# directories to ignore when looking for source files.
63
 
exclude_patterns = []
 
206
exclude_patterns = ['**/#*', '**~', '**/#*#']
64
207
 
65
 
# The reST default role (used for this markup: `text`) to use for all
66
 
# documents.
 
208
# The reST default role (used for this markup: `text`)
 
209
# to use for all documents.
67
210
#default_role = None
68
211
 
69
212
# If true, '()' will be appended to :func: etc. cross-reference text.
83
226
# A list of ignored prefixes for module index sorting.
84
227
#modindex_common_prefix = []
85
228
 
 
229
primary_domain = 'py'
 
230
nitpicky = False
 
231
 
86
232
 
87
233
# -- Options for HTML output --------------------------------------------------
88
234
 
89
235
# The theme to use for HTML and HTML Help pages.  See the documentation for
90
236
# a list of builtin themes.
91
 
html_theme_path = ['.']
92
 
html_theme = '_theme'
 
237
# html_theme_path = ['.']
 
238
# html_theme = '_theme'
93
239
 
94
240
# Theme options are theme-specific and customize the look and feel of a theme
95
241
# further.  For a list of options available for each theme, see the
120
266
# Add any paths that contain custom static files (such as style sheets) here,
121
267
# relative to this directory. They are copied after the builtin static files,
122
268
# so a file named "default.css" will overwrite the builtin "default.css".
123
 
html_static_path = ['_static']
 
269
# html_static_path = ['_static']
124
270
 
125
271
# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
126
272
# using the given strftime format.
127
273
#html_last_updated_fmt = '%b %d, %Y'
 
274
git_cmd = "git log --pretty=format:'%ad, commit %h' --date=local -n1"
 
275
html_last_updated_fmt = os.popen(git_cmd).read()
128
276
 
129
277
# If true, SmartyPants will be used to convert quotes and dashes to
130
278
# typographically correct entities.
170
318
# -- Options for LaTeX output -------------------------------------------------
171
319
 
172
320
latex_elements = {
173
 
# The paper size ('letterpaper' or 'a4paper').
174
 
#'papersize': 'letterpaper',
175
 
 
176
 
# The font size ('10pt', '11pt' or '12pt').
177
 
#'pointsize': '10pt',
178
 
 
179
 
# Additional stuff for the LaTeX preamble.
180
 
#'preamble': '',
 
321
    # The paper size ('letterpaper' or 'a4paper').
 
322
    #'papersize': 'letterpaper',
 
323
 
 
324
    # The font size ('10pt', '11pt' or '12pt').
 
325
    #'pointsize': '10pt',
 
326
 
 
327
    # Additional stuff for the LaTeX preamble.
 
328
    #'preamble': '',
181
329
}
182
330
 
183
331
# Grouping the document tree into LaTeX files. List of tuples
184
332
# (source start file, target name, title, author, documentclass [howto/manual])
185
333
latex_documents = [
186
 
  ('index', 'Heat.tex', u'Heat Documentation',
187
 
   u'Heat Developers', 'manual'),
 
334
    ('index', 'Heat.tex', u'Heat Documentation',
 
335
     u'Heat Developers', 'manual'),
188
336
]
189
337
 
190
338
# The name of an image file (relative to this directory) to place at the top of
214
362
# (source start file, name, description, authors, manual section).
215
363
man_pages = [
216
364
    ('man/heat-api', 'heat-api',
217
 
    u'REST API service to the heat project.',
218
 
    [u'Heat Developers'], 1),
 
365
     u'REST API service to the heat project.',
 
366
     [u'Heat Developers'], 1),
219
367
    ('man/heat-api-cfn', 'heat-api-cfn',
220
 
    u'CloudFormation compatible API service to the heat project.',
221
 
    [u'Heat Developers'], 1),
 
368
     u'CloudFormation compatible API service to the heat project.',
 
369
     [u'Heat Developers'], 1),
222
370
    ('man/heat-api-cloudwatch', 'heat-api-cloudwatch',
223
 
    u'CloudWatch alike API service to the heat project',
224
 
    [u'Heat Developers'], 1),
225
 
    ('man/heat-boto', 'heat-boto',
226
 
    u'Command line utility to run heat actions over the CloudFormation API',
227
 
    [u'Heat Developers'], 1),
228
 
    ('man/heat-cfn', 'heat-cfn',
229
 
    u'Command line utility to run heat actions over the CloudFormation API',
230
 
    [u'Heat Developers'], 1),
 
371
     u'CloudWatch alike API service to the heat project',
 
372
     [u'Heat Developers'], 1),
231
373
    ('man/heat-db-setup', 'heat-db-setup',
232
 
    u'Command line utility to setup the Heat database',
233
 
    [u'Heat Developers'], 1),
 
374
     u'Command line utility to setup the Heat database',
 
375
     [u'Heat Developers'], 1),
234
376
    ('man/heat-engine', 'heat-engine',
235
 
    u'Service which performs the actions from the API calls made by the user',
236
 
    [u'Heat Developers'], 1),
 
377
     u'Service which performs the actions from the API calls made by the user',
 
378
     [u'Heat Developers'], 1),
237
379
    ('man/heat-keystone-setup', 'heat-keystone-setup',
238
 
    u'Script which sets up keystone for usage by Heat',
239
 
    [u'Heat Developers'], 1),
240
 
    ('man/heat-watch', 'heat-watch',
241
 
    u'Command line utility to run heat watch actions over the CloudWatch API',
242
 
    [u'Heat Developers'], 1),
 
380
     u'Script which sets up keystone for usage by Heat',
 
381
     [u'Heat Developers'], 1),
243
382
]
244
383
 
245
384
# If true, show URL addresses after external links.
252
391
# (source start file, target name, title, author,
253
392
#  dir menu entry, description, category)
254
393
texinfo_documents = [
255
 
  ('index', 'Heat', u'Heat Documentation',
256
 
   u'Heat Developers', 'Heat', 'One line description of project.',
257
 
   'Miscellaneous'),
 
394
    ('index', 'Heat', u'Heat Documentation',
 
395
     u'Heat Developers', 'Heat', 'One line description of project.',
 
396
     'Miscellaneous'),
258
397
]
259
398
 
260
399
# Documents to append as an appendix to all manuals.