sphinx-argparse

sphinx-argparse is extension for sphinx that allows easily generate documentation for command line tools based on argparse library.

Installation

This extension is tested on python 2.7. If you have successfully used it on any other version of python, then add this info to this doc please (through gihtub pull reuqest).

Package is available in the Python Package Index:

pip install sphinx-argparse

Enable extension in your sphinx config:

extensions += ['sphinxarg.ext']

Basic usage

Extension adds “argparse” directive:

.. argparse::
   :module: my.module
   :func: my_func_that_return_parser
   :prog: fancytool

module, func and prog options are required.

For this directive to work, you should point it to the function, that will return pre-filled ArgumentParser. Something like:

def my_func_that_return_parser():
    parser = argparse.ArgumentParser()
    parser.add_argument('foo', default=False, help='foo help')
    parser.add_argument('bar', default=False)

    subparsers = parser.add_subparsers()

    subparser = subparsers.add_parser('install', help='install help')
    subparser.add_argument('ref', type=str, help='foo1 help')
    subparser.add_argument('--upgrade', action='store_true', default=False, help='foo2 help')

    return parser

Note

We will use this example as a reference for every example in this doc.

:module:
Module name, where the function is located
:func:
Function name
:prog:
It’s just name of your tool (or how it’s should appear in your documentation). Ex. if you run your script as ./boo –some args then :prog: will be “boo”

That’s it. Directive will render positional arguments, options and sub-commands.

Sub-commands are limited to one level. But, you always can output help for subcommands separately:

.. argparse::
   :module: my.module
   :func: my_func_that_return_parser
   :prog: fancytool
   :path: install

This will render same doc for “install” subcommand.

Nesting level is not limited:

.. argparse::
   :module: my.module
   :func: my_func_that_return_parser
   :prog: fancytool
   :path: install subcomand1 subcommand2 subcommand3

Extending result of argparse directive

You can add extra content or even replace some part of documentation generated by argparse directive. For example, any content you put inside directive (follow reText identation rules), will be inserted, just before argument and option list:

.. argparse::
    :module: my.module
    :func: my_func_that_return_parser
    :prog: fancytool

    My content here that will be inserted as extra, right before argument list.

    Also any valid markup...
    *************************

    ... may `be` *applied* here

    including::

         any directives you usually use.

Also, there is an option to insert own content into argument/option/subcommand description. Just create definition-list, where name is argument/option/subcommand name and definition-body is any reStructured markup:

.. argparse::
    :module: my.module
    :func: my_func_that_return_parser
    :prog: fancytool

    My content here that will be inserted as extra right before argument list.

    foo
         This text will go right after "foo" positional argument help.

    install
         This text will go right after "install" subcommand help and before it's arguments.

         --upgrade
             This text will go to upgrade option of install subcommand, nesting is not limited

You can also add classifiers to definition-list that will change behavior of content merge algorythm:

.. argparse::
    :module: my.module
    :func: my_func_that_return_parser
    :prog: fancytool

    My content that will be inserted as extra, right before argument list.

    foo : @before
         This text will go right after "foo" positional argument help.

    install : @replace
         This text will go right after "install" subcommand help and befor it's arguments.

         --upgrade : @after
             This text will go to upgrade option of install subcommand, nesting is not limited
@before
Insert content before parsed help message of argument/option/subcommand.
@after

Insert content after parsed help message of argument/option/subcommand.

This is default, if you do not specify classifier explicitly.

@replace
Replace content of help message of argument/option/subcommand.

Example structure of pages

Here is example structure of documentation for complex commands with lots of subcommands. You are free to use any structure, but this may be a good starting point.

File “index.rst”:

.. toctree::
   :maxdepth: 2

   cmd

File “cmd.rst”:

Command line utitlites
***********************

.. toctree::
   :maxdepth: 1

   cmd_main
   cmd_subcommand

File “cmd_main.rst”:

Fancytool command
***********************

.. argparse::
   :module: my.module
   :func: my_func_that_return_parser
   :prog: fancytool

   subcommand
        Here we add reference to subcommand, to simplify navigation.
        See :doc:`cmd_subcommand`

File “cmd_subcommand.rst”:

Subcommand command
***********************

.. argparse::
   :module: my.module
   :func: my_func_that_return_parser
   :prog: fancytool
   :path: subcommand

Contribution

Any help is welcome! Most wanted: * documentation correction (I am not native english speaker) * bugfixes * examples * ports for other libraries (optparse, what else?)

Contributions are accepted through github pull-request. Bug reports are also through bug-tracker on github.

https://github.com/ribozz/sphinx-argparse

Don’t forget to run tests before commit:

py.test`

Any feedback is welcome: ribozz (a) gmail dot com

Project Versions

Table Of Contents

This Page