230 lines
7.6 KiB
Python
230 lines
7.6 KiB
Python
# 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
|
|
#
|
|
# 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.
|
|
#
|
|
# nova documentation build configuration file
|
|
#
|
|
# Refer to the Sphinx documentation for advice on configuring this file:
|
|
#
|
|
# http://www.sphinx-doc.org/en/stable/config.html
|
|
|
|
import os
|
|
import sys
|
|
|
|
# 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 ----------------------------------------------------
|
|
|
|
# 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',
|
|
'sphinx.ext.todo',
|
|
'sphinx.ext.graphviz',
|
|
'openstackdocstheme',
|
|
'sphinx_feature_classification.support_matrix',
|
|
'oslo_config.sphinxconfiggen',
|
|
'oslo_config.sphinxext',
|
|
'oslo_policy.sphinxpolicygen',
|
|
'oslo_policy.sphinxext',
|
|
'ext.versioned_notifications',
|
|
'ext.feature_matrix',
|
|
'sphinxcontrib.actdiag',
|
|
'sphinxcontrib.seqdiag',
|
|
]
|
|
|
|
# openstackdocstheme options
|
|
repository_name = 'openstack/nova'
|
|
bug_project = 'nova'
|
|
bug_tag = 'doc'
|
|
|
|
config_generator_config_file = '../../etc/nova/nova-config-generator.conf'
|
|
sample_config_basename = '_static/nova'
|
|
|
|
policy_generator_config_file = [
|
|
('../../etc/nova/nova-policy-generator.conf', '_static/nova'),
|
|
]
|
|
|
|
actdiag_html_image_format = 'SVG'
|
|
actdiag_antialias = True
|
|
|
|
seqdiag_html_image_format = 'SVG'
|
|
seqdiag_antialias = True
|
|
|
|
todo_include_todos = True
|
|
|
|
# The master toctree document.
|
|
master_doc = 'index'
|
|
|
|
# General information about the project.
|
|
copyright = u'2010-present, OpenStack Foundation'
|
|
|
|
# The name of the Pygments (syntax highlighting) style to use.
|
|
pygments_style = 'sphinx'
|
|
|
|
# -- Options for man page output ----------------------------------------------
|
|
|
|
# Grouping the document tree for man pages.
|
|
# List of tuples 'sourcefile', 'target', u'title', u'Authors name', 'manual'
|
|
|
|
_man_pages = [
|
|
('nova-api-metadata', u'Cloud controller fabric'),
|
|
('nova-api-os-compute', u'Cloud controller fabric'),
|
|
('nova-api', u'Cloud controller fabric'),
|
|
('nova-compute', u'Cloud controller fabric'),
|
|
('nova-console', u'Cloud controller fabric'),
|
|
('nova-dhcpbridge', u'Cloud controller fabric'),
|
|
('nova-manage', u'Cloud controller fabric'),
|
|
('nova-network', u'Cloud controller fabric'),
|
|
('nova-novncproxy', u'Cloud controller fabric'),
|
|
('nova-spicehtml5proxy', u'Cloud controller fabric'),
|
|
('nova-serialproxy', u'Cloud controller fabric'),
|
|
('nova-rootwrap', u'Cloud controller fabric'),
|
|
('nova-scheduler', u'Cloud controller fabric'),
|
|
('nova-xvpvncproxy', u'Cloud controller fabric'),
|
|
('nova-conductor', u'Cloud controller fabric'),
|
|
]
|
|
|
|
man_pages = [
|
|
('cli/%s' % name, name, description, [u'OpenStack'], 1)
|
|
for name, description in _man_pages]
|
|
|
|
# -- Options for HTML output --------------------------------------------------
|
|
|
|
# The theme to use for HTML and HTML Help pages. Major themes that come with
|
|
# Sphinx are currently 'default' and 'sphinxdoc'.
|
|
html_theme = 'openstackdocs'
|
|
|
|
# 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']
|
|
|
|
# Add any paths that contain "extra" files, such as .htaccess or
|
|
# robots.txt.
|
|
html_extra_path = ['_extra']
|
|
|
|
|
|
# -- Options for LaTeX output -------------------------------------------------
|
|
|
|
# Grouping the document tree into LaTeX files. List of tuples
|
|
# (source start file, target name, title, author, documentclass
|
|
# [howto/manual]).
|
|
latex_documents = [
|
|
('index', 'Nova.tex', u'Nova Documentation',
|
|
u'OpenStack Foundation', 'manual'),
|
|
]
|
|
|
|
|
|
# -- Options for openstackdocstheme -------------------------------------------
|
|
|
|
# keep this ordered to keep mriedem happy
|
|
#
|
|
# NOTE(stephenfin): Projects that don't have a release branch, like TripleO and
|
|
# reno, should not be included here
|
|
openstack_projects = [
|
|
'ceilometer',
|
|
'cinder',
|
|
'glance',
|
|
'horizon',
|
|
'ironic',
|
|
'keystone',
|
|
'neutron',
|
|
'nova',
|
|
'oslo.log',
|
|
'oslo.messaging',
|
|
'oslo.i18n',
|
|
'oslo.versionedobjects',
|
|
'placement',
|
|
'python-novaclient',
|
|
'python-openstackclient',
|
|
'watcher',
|
|
]
|
|
# -- Custom extensions --------------------------------------------------------
|
|
|
|
# NOTE(mdbooth): (2019-03-20) Sphinx loads policies defined in setup.cfg, which
|
|
# includes the placement policy at nova/api/openstack/placement/policies.py.
|
|
# Loading this imports nova/api/openstack/__init__.py, which imports
|
|
# nova.monkey_patch, which will do eventlet monkey patching to the sphinx
|
|
# process. As well as being unnecessary and a bad idea, this breaks on
|
|
# python3.6 (but not python3.7), so don't do that.
|
|
os.environ['OS_NOVA_DISABLE_EVENTLET_PATCHING'] = '1'
|
|
|
|
|
|
def monkey_patch_blockdiag():
|
|
"""Monkey patch the blockdiag library.
|
|
|
|
The default word wrapping in blockdiag is poor, and breaks on a fixed
|
|
text width rather than on word boundaries. There's a patch submitted to
|
|
resolve this [1]_ but it's unlikely to merge anytime soon.
|
|
|
|
In addition, blockdiag monkey patches a core library function,
|
|
``codecs.getreader`` [2]_, to work around some Python 3 issues. Because
|
|
this operates in the same environment as other code that uses this library,
|
|
it ends up causing issues elsewhere. We undo these destructive changes
|
|
pending a fix.
|
|
|
|
TODO: Remove this once blockdiag is bumped to 1.6, which will hopefully
|
|
include the fix.
|
|
|
|
.. [1] https://bitbucket.org/blockdiag/blockdiag/pull-requests/16/
|
|
.. [2] https://bitbucket.org/blockdiag/blockdiag/src/1.5.3/src/blockdiag/utils/compat.py # noqa
|
|
"""
|
|
import codecs
|
|
from codecs import getreader
|
|
|
|
from blockdiag.imagedraw import textfolder
|
|
|
|
# oh, blockdiag. Let's undo the mess you made.
|
|
codecs.getreader = getreader
|
|
|
|
def splitlabel(text):
|
|
"""Split text to lines as generator.
|
|
|
|
Every line will be stripped. If text includes characters "\n\n", treat
|
|
as line separator. Ignore '\n' to allow line wrapping.
|
|
"""
|
|
lines = [x.strip() for x in text.splitlines()]
|
|
out = []
|
|
|
|
for line in lines:
|
|
if line:
|
|
out.append(line)
|
|
else:
|
|
yield ' '.join(out)
|
|
out = []
|
|
|
|
yield ' '.join(out)
|
|
|
|
def splittext(metrics, text, bound, measure='width'):
|
|
folded = [' ']
|
|
for word in text.split():
|
|
# Try appending the word to the last line
|
|
tryline = ' '.join([folded[-1], word]).strip()
|
|
textsize = metrics.textsize(tryline)
|
|
if getattr(textsize, measure) > bound:
|
|
# Start a new line. Appends `word` even if > bound.
|
|
folded.append(word)
|
|
else:
|
|
folded[-1] = tryline
|
|
return folded
|
|
|
|
# monkey patch those babies
|
|
textfolder.splitlabel = splitlabel
|
|
textfolder.splittext = splittext
|
|
|
|
|
|
monkey_patch_blockdiag()
|