Method generate_api_doc

docs/sphinxext/apigen.py:243–307

Make autodoc documentation template string for a module Parameters ---------- uri : string python location of module - e.g 'sphinx.builder' Returns ------- S : string Contents of API doc

(self, uri)

            return self._parse_module(uri)

    def generate_api_doc(self, uri):
        '''Make autodoc documentation template string for a module

        Parameters
        ----------
        uri : string
            python location of module - e.g 'sphinx.builder'

        Returns
        -------
        S : string
            Contents of API doc
        '''
        # get the names of all classes and functions
        functions, classes = self.find_funcs_classes(uri)
        if not len(functions) and not len(classes):
            #print ('WARNING: Empty -', uri)  # dbg
            return ''

        # Make a shorter version of the uri that omits the package name for
        # titles
        uri_short = re.sub(r'^%s\.' % self.package_name,'',uri)

        ad = '.. AUTO-GENERATED FILE -- DO NOT EDIT!\n\n'

        # Set the chapter title to read 'Module:' for all modules except for the
        # main packages
        if '.' in uri:
            chap_title = 'Module: :mod:`' + uri_short + '`'
        else:
            chap_title = ':mod:`' + uri_short + '`'
        ad += chap_title + '\n' + self.rst_section_levels[1] * len(chap_title)

        ad += '\n.. automodule:: ' + uri + '\n'
        ad += '\n.. currentmodule:: ' + uri + '\n'
        
        if classes:
            subhead = str(len(classes)) + (' Classes' if len(classes) > 1 else ' Class')
            ad += '\n'+ subhead + '\n' + \
                  self.rst_section_levels[2] * len(subhead) + '\n'

        for c in classes:
            opts = c.sphinx_options
            ad += "\n.. autoclass:: " + c.name + "\n"
            # must NOT exclude from index to keep cross-refs working
            ad += "  :members:\n"
            if opts.get("show_inheritance", True):
                ad += "  :show-inheritance:\n"
            if opts.get("show_inherited_members", False):
                exclusions_list = opts.get("exclude_inherited_from", [])
                exclusions = (
                    (" " + " ".join(exclusions_list)) if exclusions_list else ""
                )
                ad += f"  :inherited-members:{exclusions}\n"
            if c.has_init:
                  ad += '\n  .. automethod:: __init__\n'
        
        if functions: