sphinxgen python package

• sphinxgen.version module

A utility module for generating basic sphinx rest files for each module and package specified, recursively.

Note

Please forgive me for this crappy code and crappier documentation. I hacked this together while working on another project. It’s worth refactoring, if you’d like to do so, please feel free and send me a pull request: https://bitbucket.org/bmearns/sphinxgen

class sphinxgen.TemplateLoader(args)

Bases: jinja2.loaders.BaseLoader

A jinja2 template loaded that loads templates needed by SphinxGen.

get_source(environment, template)

Returns the source for the named template.

class sphinxgen.SphinxGen(parsed_args, log=None)

Bases: object

The class that actually does the work.

Initializing an instance runs the operation as well.

Parameters:parsed_args – This should be the namespace object returned by the argument_parser after parsing the command line options.

generate_output(template, context, opath)

Writes output to the specified file. Given a jinja2 template object and the context for the template, it renders the template and writes the results to the specified path.

If the path exists, it is not modified unless overwrite is set. If dry_run is set, no output is actually generated.

build_package(package_name, package_dir, output_dir)

Does all the work (recursively) for a particular package, which is a directory with an __init__.py file in it. Returns None if the specified directory (package_dir) is not actually a package (has not __init__.py file). Otherwise returns a dictionary representing the some basic information about the package, it’s subpackages, and its submodules (python files in the package directory).

Generates the file for the package as well, plus all it’s submodules, and all its sub packages. This is done through generate_output, so if dry_run is set, nothing will actually be written out.

sphinxgen.argument_parser = ArgumentParser(prog='sphinxgen', usage='\n %(prog)s [options] PACKAGE_DIR [PACKAGE_DIR [...]]\n %(prog)s [options] --dump-templates TEMPLATE_DIR [PACKAGE_DIR [...]]\n %(prog)s --help\n', description='Generate sphinx stub files for all modules in a python package.', version=None, formatter_class=<class 'argparse.RawDescriptionHelpFormatter'>, conflict_handler='error', add_help=True)

An ArgumentParser instance that can be used to parse the command line options for the command line program. It is populated when the module is constructed.

sphinxgen.main(args=None)

The command line program. If this module is invoked as the main module, this function is called.

This simply parses the args with argument_parser, and passes them on to the SphinxGen factory method.

Parameters:args – A sequence of command line arguments (like sys.argv) or None (in which case sys.argv is used).

class sphinxgen.sphinxgen(dist, **kw)

Bases: setuptools.Command

A setuptools setuptools.Command for running SphinxGen.

description = 'Generate base sphinx ReST files for python packages and modules.'

user_options = [('output=', 'o', 'The directory where output will be written. The default is the current directory.'), ('prefix=', None, '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', None, 'Overwrite any existing files.'), ('dry-run', 'n', 'Do a dry run, do not actually generate any files, just print what would happen if we did.'), ('index=', None, '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', None, 'Do not generate an index file.'), ('no-modules', None, 'Do not generate separate files for modules, only packages.'), ('package-template=', None, 'The path to the jinja2 template file to use for generating package files. If not given, a built-in template will be used.'), ('module-template=', None, '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=', None, '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=', None, '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', None, 'Print detailed logs for debugging.'), ('version', None, ''), ('package-dirs', None, 'The package directories to process.')]

initialize_options()

finalize_options()

run()