def run(self):
rst = ViewList()
unit_database = UnitDatabase.GetSingleton()
source = "fakefile.rst"
# Create the rst content
for category in sorted(unit_database.IterCategories(),
key=str.casefold):
title = unit_database.GetCategoryInfo(category).caption.title()
rst.append(f".. rubric:: {title}", source)
rst.append(f"", source)
for unit in sorted(
unit_database.GetCategoryInfo(category).valid_units_set,
key=str.casefold):
name = unit_database.unit_to_unit_info[unit].name
rst.append(f'- ``"{unit}"`` ({name})', source)
rst.append(f" ", source)
# Create a node.
node = nodes.section()
node.document = self.state.document
# Parse the rst.
nested_parse_with_titles(self.state, rst, node)
# And return the result.
return node.children
def _parse(self, rst_text, annotation):
result = ViewList()
for line in rst_text.split("\n"):
result.append(line, annotation)
node = nodes.paragraph()
node.document = self.state.document
nested_parse_with_titles(self.state, result, node)
return node.children
def parse_content(state, content: StringList) -> List[nodes.Node]:
"""Given a reStructured text representation of some content format parse it
into a list of nodes."""
section = nodes.section()
section.document = state.document
nested_parse_with_titles(state, content, section)
return section.children
def run(self):
self.assert_has_content()
text = '\n'.join(self.content)
node = callout(text, **self.options)
node.document = self.state.document
set_source_info(self, node)
node['classes'] += ['bs-callout', self.node_class]
if 'title' in self.options:
title = self.get_title_node()
node += title
nested_parse_with_titles(self.state, self.content, node)
self.add_name(node)
return [node]
def run(self):
self.filename_set = set() # a set of dependent filenames
self.reporter = self.state.document.reporter
self.env = self.state.document.settings.env
self.warnings = []
self.result = ViewList()
# find out what documenter to call
objtype = self.name[4:]
doc_class = self._registry[objtype]
# process the options with the selected documenter's option_spec
self.genopt = Options(
assemble_option_dict(self.options.items(), doc_class.option_spec)
)
# generate the output
documenter = doc_class(self, self.arguments[0])
documenter.generate(more_content=self.content)
if not self.result:
return self.warnings
# record all filenames as dependencies -- this will at least
# partially make automatic invalidation possible
for fn in self.filename_set:
self.env.note_dependency(fn)
# use a custom reporter that correctly assigns lines to source
# filename/description and lineno
old_reporter = self.state.memo.reporter
self.state.memo.reporter = AutodocReporter(
self.result, self.state.memo.reporter
)
if self.name == "automodule":
node = nodes.section()
# necessary so that the child nodes get the right source/line set
node.document = self.state.document
nested_parse_with_titles(self.state, self.result, node)
else:
node = nodes.paragraph()
node.document = self.state.document
self.state.nested_parse(self.result, 0, node)
self.state.memo.reporter = old_reporter
return self.warnings + node.children
def run(self):
tags_arg = self.options.get("tags")
tags = {t.strip() for t in tags_arg.split(",")} if tags_arg else None
header_separator = self.options.get('header-separator')
new_content = self.render_content(tags=tags, header_separator=header_separator)
with switch_source_input(self.state, self.content):
new_content = StringList(new_content.splitlines(), source='')
node = nodes.section() # type: Element
# necessary so that the child nodes get the right source/line set
node.document = self.state.document
nested_parse_with_titles(self.state, new_content, node)
# record all filenames as dependencies -- this will at least
# partially make automatic invalidation possible
for filepath in get_provider_yaml_paths():
self.state.document.settings.record_dependencies.add(filepath)
return node.children
def run(self):
self.filename_set = set() # a set of dependent filenames
self.reporter = self.state.document.reporter
self.env = self.state.document.settings.env
self.warnings = []
self.result = ViewList()
# find out what documenter to call
objtype = self.name[4:]
doc_class = self._registry[objtype]
# process the options with the selected documenter's option_spec
self.genopt = Options(assemble_option_dict(
self.options.items(), doc_class.option_spec))
# generate the output
documenter = doc_class(self, self.arguments[0])
documenter.generate(more_content=self.content)
if not self.result:
return self.warnings
# record all filenames as dependencies -- this will at least
# partially make automatic invalidation possible
for fn in self.filename_set:
self.env.note_dependency(fn)
# use a custom reporter that correctly assigns lines to source
# filename/description and lineno
old_reporter = self.state.memo.reporter
self.state.memo.reporter = AutodocReporter(self.result,
self.state.memo.reporter)
if self.name == 'automodule':
node = nodes.section()
# necessary so that the child nodes get the right source/line set
node.document = self.state.document
nested_parse_with_titles(self.state, self.result, node)
else:
node = nodes.paragraph()
node.document = self.state.document
self.state.nested_parse(self.result, 0, node)
self.state.memo.reporter = old_reporter
return self.warnings + node.children
def _auto_directive(dirname, arguments, options, content, lineno,
content_offset, block_text, state, state_machine):
what = dirname[4:] # strip "auto"
name = arguments[0]
genopt = Options()
members = options.get('members', [])
genopt.inherited_members = 'inherited-members' in options
if genopt.inherited_members and not members:
# :inherited-members: implies :members:
members = ['__all__']
genopt.undoc_members = 'undoc-members' in options
genopt.show_inheritance = 'show-inheritance' in options
genopt.noindex = 'noindex' in options
genopt.synopsis = options.get('synopsis', '')
genopt.platform = options.get('platform', '')
genopt.deprecated = 'deprecated' in options
generator = RstGenerator(genopt, state.document, lineno)
generator.generate(what, name, members, content)
if not generator.result:
return generator.warnings
# record all filenames as dependencies -- this will at least partially make
# automatic invalidation possible
for fn in generator.filename_set:
state.document.settings.env.note_dependency(fn)
# use a custom reporter that correctly assigns lines to source and lineno
old_reporter = state.memo.reporter
state.memo.reporter = AutodocReporter(generator.result, state.memo.reporter)
if dirname == 'automodule':
node = nodes.section()
nested_parse_with_titles(state, generator.result, node)
else:
node = nodes.paragraph()
state.nested_parse(generator.result, 0, node)
state.memo.reporter = old_reporter
return generator.warnings + node.children
def _parse_string_list(string_list, node, state):
nested_parse_with_titles(state, string_list, node)
def run(self):
"""Load and document the current config options."""
cindershell = shell.OpenStackCinderShell()
parser = cindershell.get_base_parser()
api_version = api_versions.APIVersion(api_versions.MAX_VERSION)
LOG.info('Generating CLI docs %s', api_version)
cindershell.get_subcommand_parser(api_version, False, [])
result = sm.ViewList()
source = '<{}>'.format(__name__)
result.append('.. _cinder_command_usage:', source)
result.append('', source)
result.append('cinder usage', source)
result.append('------------', source)
result.append('', source)
result.append('.. code-block:: console', source)
result.append('', source)
result.append('', source)
usage = self._get_usage_lines(parser.format_usage(),
'<subcommand> ...')
for line in usage:
result.append(' {}'.format(line), source)
result.append('', source)
result.append('.. _cinder_command_options:', source)
result.append('', source)
result.append('Optional Arguments', source)
result.append('~~~~~~~~~~~~~~~~~~', source)
result.append('', source)
# This accesses a private variable from argparse. That's a little
# risky, but since this is just for the docs and not "production" code,
# and since this variable hasn't changed in years, it's a calculated
# risk to make this documentation generation easier. But if something
# suddenly breaks, check here first.
actions = sorted(parser._actions, key=lambda x: x.option_strings[0])
for action in actions:
if action.help == '==SUPPRESS==':
continue
opts = ', '.join(action.option_strings)
result.append('``{}``'.format(opts), source)
result.append(' {}'.format(action.help), source)
result.append('', source)
result.append('', source)
result.append('.. _cinder_commands:', source)
result.append('', source)
result.append('Commands', source)
result.append('~~~~~~~~', source)
result.append('', source)
for cmd in cindershell.subcommands:
if 'completion' in cmd:
continue
result.append('``{}``'.format(cmd), source)
subcmd = cindershell.subcommands[cmd]
description = self._format_description_lines(subcmd.description)
result.append(' {}'.format(description[0]), source)
result.append('', source)
result.append('', source)
result.append('.. _cinder_command_details:', source)
result.append('', source)
result.append('Command Details', source)
result.append('---------------', source)
result.append('', source)
for cmd in cindershell.subcommands:
if 'completion' in cmd:
continue
subcmd = cindershell.subcommands[cmd]
result.append('.. _cinder{}:'.format(cmd), source)
result.append('', source)
result.append(subcmd.prog, source)
result.append('~' * len(subcmd.prog), source)
result.append('', source)
result.append('.. code-block:: console', source)
result.append('', source)
usage = self._get_usage_lines(subcmd.format_usage())
for line in usage:
result.append(' {}'.format(line), source)
result.append('', source)
description = self._format_description_lines(subcmd.description)
result.append(description[0], source)
result.append('', source)
if len(subcmd._actions) == 0:
continue
positional = []
optional = []
for action in subcmd._actions:
if len(action.option_strings):
if (action.option_strings[0] != '-h'
and action.help != '==SUPPRESS=='):
optional.append(action)
else:
positional.append(action)
if positional:
result.append('**Positional arguments:**', source)
result.append('', source)
for action in positional:
result.append('``{}``'.format(action.metavar), source)
result.append(' {}'.format(action.help), source)
result.append('', source)
if optional:
result.append('**Optional arguments:**', source)
result.append('', source)
for action in optional:
result.append(
'``{} {}``'.format(', '.join(action.option_strings),
action.metavar), source)
result.append(' {}'.format(action.help), source)
result.append('', source)
node = nodes.section()
node.document = self.state.document
nested_parse_with_titles(self.state, result, node)
return node.children
def render_content(self, doc_stripped):
doc_stripped_view = ViewList(prepare_docstring(doc_stripped))
doc_stripped_node = nodes.container()
nested_parse_with_titles(self.state, doc_stripped_view,
doc_stripped_node)
return doc_stripped_node