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.