Basic Usage¶

The most basic usage is to simple invoke sphinxgen from the command line, passing as arguments the file-system path to whatever python package you want to generate files for. Note that a python package is a directory containing an __init__.py file.

> sphinxgen src/python/my_package

The program will generate a file for the package, plus one file for each module it finds in the package. Additionally, if the package contains any subpackages, it will recurse into those packages as well, generating one file for each package and one file for each module. Lastly, it will generate an index file to summarize all of the top-level packages it processed.

If you want to generate files for multiple packages, specify each package as an argument:

> sphinxgen src/python/my_package src/python/another_package src/python/etc

To control the directory where the files are generated, use the --output option:

> sphinxgen --output sphinx-files src/python/my_package

Template Files¶

Output is based on templates, specifically jinja templates. There is a separate template file for packages, modules, and the index. By default, there are internal templates built into the program which are used, but you can override any or all of these with your own template files using the --package-templte, --module-template, and --index-template options.

Additionally, each individual generated file can have its own template by creating a template file of the same name inside the template directory. This is useful for having custom files for certain modules or packages. Watch the output of the command to see the names of the files it generates.

Note that since there is only one index file, it always uses the template specified by the --index-template option (or the built-in index template if this option is not given). This is true even if there is a file in the template-directory which has the same name as the generated index file (e.g., as specified by the --index option).

For more information on writing template files, see Jinja Template Contexts.

Example Usages¶

> PACKAGE_1=src/python/frob
> PACkAGE_2=src/python/baz
> ls -R $PACKAGE_1
src/python/frob:
__init__.py  frobnicate.py  version.py

> ls -R $PACKAGE_2
src/python/baz:
__init__.py  foo  util.py  version.py

src/python/baz/foo:
__init__.py  bar.py

> sphinxgen -o sphinx/source --prefix code_ $PACKAGE_1 $PACKAGE_2
sphinxgen: Generating sphinx\source\code_frob.rst
sphinxgen: Generating sphinx\source\code_frob.frobnicate.rst
sphinxgen: Generating sphinx\source\code_frob.version.rst
sphinxgen: Generating sphinx\source\code_baz.foo.rst
sphinxgen: Generating sphinx\source\code_baz.foo.bar.rst
sphinxgen: Generating sphinx\source\code_baz.rst
sphinxgen: Generating sphinx\source\code_baz.util.rst
sphinxgen: Generating sphinx\source\code_baz.version.rst
sphinxgen: Generating sphinx\source\code_index.rst

> TEMPLATE_DIR=sphinx/source/_sphinxgen
> mkdir $TEMPLATE_DIR
> touch $TEMPLATE_DIR/code_baz.util.rst
> sphinxgen -o sphinx/source --prefix code_ --overwrite \
    --template-dir $TEMPLATE_DIR $PACKAGE_1 $PACKAGE_2
sphinxgen: Generating sphinx\source\code_frob.rst
sphinxgen: Generating sphinx\source\code_frob.frobnicate.rst
sphinxgen: Generating sphinx\source\code_frob.version.rst
sphinxgen: Generating sphinx\source\code_baz.foo.rst
sphinxgen: Generating sphinx\source\code_baz.foo.bar.rst
sphinxgen: Generating sphinx\source\code_baz.rst
sphinxgen: Found template file for code_baz.util.rst
sphinxgen: Generating sphinx\source\code_baz.util.rst
sphinxgen: Generating sphinx\source\code_baz.version.rst
sphinxgen: Generating sphinx\source\code_index.rst

>

Command Line Interface¶

sphinxgen¶

Generate sphinx stub files for all modules in a python package.

package_dir¶: The package directories to process.

-h, --help¶: show this help message and exit

-o <output>, --output <output>¶: The directory where output will be written. The default is the current directory.

--prefix <prefix>¶: A prefix to use for every generated file name. If –index is used, the prefix will not be used for the generated index file.

--overwrite¶: Overwrite any existing files.

-n, --dry-run¶: Do a dry run, do not actually generate any files, just print what would happen if we did.

--index <path>¶: The path to the index file to generate (without extension). The default is “index”, with appropriate prefix as specified by the –prefix option. if you explicitly use this option, the prefix will not be added.

--no-index¶: Do not generate an index file.

--no-modules¶: Do not generate separate files for modules, only packages.

--template-dir <dir>¶: The path to the base directory template files. This effects the resolution of paths specified for –package-template, –module-template, and –index-template, as well as any templates referenced from those templates. Templates referenced by absolute file-system path will be accessed directly, while templates referenced by any relative path will be loaded relative to this directory. The default is the current directory.

--package-template <path>¶: The path to the jinja2 template file to use for generating package files. If not given, a built-in template will be used. Note that relative paths are resolved relative to the –template-dir.

--module-template <path>¶: The path to the jinja2 template file to use for generating module files. See –package-template for more details. The default is “module.rst”.

--index-template <path>¶: The path to the jinja2 template file to use for generating the index file. See –package-template for more details. The default is “index.rst”.

--dump-templates <template_dir>¶: Dump the built-in template files to the specified directory. This is useful as a starting point for creating your own template files. The template files are named package.rst, module.rst, and index.rst.

--debug¶: Print detailed logs for debugging.

--version¶: show program’s version number and exit