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:

1. 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!
   ]
   

2. 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_name
   

   Or 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: 2
   

3. Make sure your executable scripts:

   1. use ArgumentParser rather than OptionParser or getopt for argument parsing
   2. 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.