Advanced usage

Preventing sphinxcontrib-argdoc from processing one or more, but not all scripts, in a package

To prevent sphinxcontrib.argdoc from processing a main-like function, in one of the executable scripts in your package, use the noargdoc() function decorator. For example:

#!/usr/bin/env python
import argparse
from sphinxcontrib.argdoc import noargdoc

@noargdoc
def main():
    """Main-like function that would normally be processed by
    `sphinxcontrib-argdoc` but that will instead be skipped!
    """
    # main function body here
    parser = argparse.ArgumentParser()
    pass

if __name__ == "__main__":
    main()

Processing a main-like function named something other than main

If your code conventions use a name different from main for main-like functions, sphinxcontrib.argdoc can still process these. Just set the value of the configuration parameter argdoc_main_func to your function name in conf.py:

...

# somewhere in conf.py
argdoc_main_func = "whatever_we_call_main_funcs_at_our_organization"

...

Using alternate prefix characters in your ArgumentParser

If your executable script uses one or more alternate prefix characters (e.g. ‘+’ instead of or in addition to ‘-‘, set the configuration parameter argdoc_prefix_chars to a string containing all of the prefix characters used by all of your scripts in your conf.py:

# somewhere in conf.py
argdoc_prefix_chars = "-+" # our scripts use both '-' and '+' to prefix optional arguments

Debugging sphinxcontrib.argdoc output

To save a snapshot of the raw reStructuredText generated by argdoc for each file after processing, set argdoc_save_rst to True in your conf.py. In your build folder, you will find files names X_postargdoc.rst where X corresponds to the name of the rst stub file.