Quickstart¶
Installation¶
Install stable versions via pip. For a single-user installation:
$ pip install --user sphinxcontrib-argdoc
For a system-wide installation:
$ sudo pip install sphinxcontrib-argdoc
Using sphinxcontrib.argdoc
in your project¶
Setting up sphinxcontrib.argdoc
only takes a few steps:
Find the extensions definition in your Sphinx configuration file,
conf.py
, and add ‘sphinxcontrib.argdoc’ to the list. For example:# inside conf.py extensions = [ 'sphinx.ext.autodoc', 'sphinx.ext.autosummary', 'sphinx.ext.intersphinx', 'sphinxcontrib.argdoc' # <---- ta-da! ]Generate document stubs for your package. It is easiest to use sphinx-apidoc. From the terminal:
$ cd my_project_folder/my_package_folder $ sphinx-apidoc -e -o docs/source/generated my_package_nameOr you can make your document stubs manually. Just make sure the final document stubs for your executable scripts include the
.. automodule :
directive. A stub file for a demo script (e.g.demo.rst
) might look like this:`argdoc` demo script ==================== .. automodule:: some_package.some_module :members: :undoc-members: :show-inheritance: .. toctree:: :maxdepth: 2Make sure your executable scripts:
- use
ArgumentParser
rather thanOptionParser
orgetopt
for argument parsing- contain a main-like function (typically called main) that is called when the script is executed from the shell.
If you want your documentation to be extra nice, write a user-friendly description of your script in its module docstring, and pass the docstring contents as a description to your
ArgumentParser
. For example:#!/usr/bin/env python """This is my module docstring, which describes what my script does at length, so that users can figure out what it does. Conveniently this text is used both by argparse as help text in the shell, and by Sphinx when generating HTML documentation. """ import argparse # other functions et c here pass def main(): """This is the body of the program""" my_parser = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter) my_parser.add_argument("some_arg",type=str,help="some helptext, if you want") my_parser.add_argument("--some_keyword",type=int,help="Some other helptext") # et c. other options & program body args = argparse.parse_args() # rest of main() pass if __name__ == "__main__": main()That’s it! There is nothing else you need to do. For further info or configuration options, see Advanced usage. For examples, see Examples.
Warning
sphinxcontrib.argdoc
generates its documentation by calling your executable scripts with the argument--help
. Therefore, any side effects caused by executing your script will take effect during the documentation build process.