Customize templates for `sphinx-apidoc`

Question

I\'ve recently tried using sphinx-apidoc from Sphinx to help generate Sphinx specific reStructuredText from the API of a Python project.

However, the result I\'m get

Answer 1

The sphinx-apidoc script uses the apidoc.py module. I am not able to provide detailed instructions, but in order to remove headings or otherwise customize the output, you'll have to write your own version of this module. There is no other "template".

Note that if the API and module structure is stable, there is no need to run sphinx-apidoc repeatedly. You can post-process the generated rst files to your liking once and then place them under version control. See also https://stackoverflow.com/a/28481785/407651.

Update

From Sphinx 2.2.0, sphinx-apidoc supports templates. See https://stackoverflow.com/a/57520238/407651.

Answer 2

FWIW, here's a complete hack of a script to make your desired changes, which were also my desired changes, in a "filename.rst.new" file next to each "filename.rst":

#!/usr/bin/env python

'''
Rearrange content in sphinx-apidoc generated .rst files.

* Move "Module Contents" section to the top.
* Remove headers for "Module Contents", "Submodules" and "Subpackages",
  including their underlines and the following blank line.
'''


import argparse
import glob
import os


# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
def argument_parser():
    '''
    Define command line arguments.
    '''

    parser = argparse.ArgumentParser(
        description='''
        Rearrange content in sphinx-apidoc generated .rst files.
        '''
        )

    parser.add_argument(
        '-v', '--verbose',
        dest='verbose',
        default=False,
        action='store_true',
        help="""
            show more output.
            """
        )

    parser.add_argument(
        'input_file',
        metavar="INPUT_FILE",
        nargs='+',
        help="""
            file.
            """
        )

    return parser


# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
def main():
    '''
    Main program entry point.
    '''

    global args
    parser = argument_parser()
    args = parser.parse_args()

    filenames = [glob.glob(x) for x in args.input_file]
    if len(filenames) > 0:
        filenames = reduce(lambda x, y: x + y, filenames)

    for filename in set(filenames):

        # line_num was going to be for some consistency checks, never
        # implemented but left in place.
        found = {
            'Subpackages': {'contents': False, 'line_num': None},
            'Submodules': {'contents': False, 'line_num': None},
            'Module contents': {'contents': True, 'line_num': None},
            }

        in_module_contents = False
        line_num = 0
        reordered = []
        module_contents = []

        new_filename = '.'.join([filename, 'new'])

        with open(filename, 'r') as fptr:

            for line in fptr:
                line = line.rstrip()
                discard = False

                line_num += 1

                if (
                        in_module_contents
                        and len(line) > 0
                        and line[0] not in ['.', '-', ' ']
                        ):  # pylint: disable=bad-continuation
                    in_module_contents = False

                for sought in found:

                    if line.find(sought) == 0:

                        found[sought]['line_num'] = line_num
                        if found[sought]['contents']:
                            in_module_contents = True

                        discard = True
                        # discard the underlines and a blank line too
                        _ = fptr.next()
                        _ = fptr.next()

                if in_module_contents and not discard:
                    module_contents.append(line)

                elif not discard:
                    reordered.append(line)

                # print '{:<6}|{}'.format(len(line), line)

        with open(new_filename, 'w') as fptr:
            fptr.write('\n'.join(reordered[:3]))
            fptr.write('\n')
            if module_contents:
                fptr.write('\n'.join(module_contents))
                fptr.write('\n')
                if len(module_contents[-1]) > 0:
                    fptr.write('\n')
            if reordered[3:]:
                fptr.write('\n'.join(reordered[3:]))
                fptr.write('\n')


if __name__ == "__main__":
    main()

Answer 3

I implemented better-apidoc, a patched version of the sphinx-apidoc script that adds full support for templates.

It adds a -t/--template option, allowing to pass a template directory that must contain template files package.rst and module.rst. See package.rst and module.rst for an example. These render to e.g. http://qnet.readthedocs.io/en/latest/API/qnet.algebra.operator_algebra.html.