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