Ejemplo n.º 1
0
    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
Ejemplo n.º 2
0
 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
Ejemplo n.º 3
0
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
Ejemplo n.º 4
0
    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]
Ejemplo n.º 5
0
    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
Ejemplo n.º 7
0
    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
Ejemplo n.º 8
0
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
Ejemplo n.º 9
0
def _parse_string_list(string_list, node, state):
    nested_parse_with_titles(state, string_list, node)
Ejemplo n.º 10
0
    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
Ejemplo n.º 11
0
 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