Python package documentation generation tool.

Note

This page is a reference documentation. It only explains the class signature, and not how to use it. Please refer to the gallery for the big picture.

class pysphinxdoc.docgen.DocHelperWriter(path_module, outdir, module_names, root_module_name, generate_examples=False, rst_extension='.rst', verbose=0)[source]¶

Bases: object

A basic class to create the Sphinx complient documentation of a module.

Note

Please use directly the sphinxdoc script.

Initialize the DocHelperWriter class.

Parameters:

path_module : str (mandatory)

the path to the module to be documented.

outdir : str (mandatory)

the path where the documentation will be generated. Expect a ‘$outdir/source/_static’ folder containing a logo named ‘$name_module.png’ and an ‘carousel’ subfolder containing a list of images to be displayed in the banner.

module_names : list of str (mandatory)

List of modules defined in the project (ie. the output of ‘setuptools.find_packages’)

root_module_name : str (mandatory)

The name of the python package to be documented.

generate_examples : bool (optional, default False)

If set, generates the gallery examples from the package scripts.

rst_extension : string (optional)

Extension for reST files, default ‘.rst’.

verbose : int (optional)

The verbosity level, default 0.

format_with_dict(string, dictionary)[source]¶

Use regular expressions to replace % by %% where % is not followed by (. Avoid “not enough arguments for format string” errors.

Parameters:

string : str

a string to be formated.

dictionary : dict

a mapping used to edit the input string.

generate_documentation_index_entry(module_name, indent=4)[source]¶

Generate a new entry in the dicumentation index.

Parameters:

module_name : string

the name of the module we want to index.

ident : int

the number of blank prefix.

Returns:

ad : string

the reST formated index description.

getalias(members, alias_map)[source]¶: Return all the object alias within a module.

getmembers(mod)[source]¶: Return the members of a module.

rst2html(rst, indent=4)[source]¶

Convert a reST formated string to a HTML string.

Parameters:

rst : str (mandatory)

the rst formated string.

ident : int

the number of blank prefix.

Returns:

out : str

the html formated string.

title_for(title)[source]¶

Create a title from a underscore-separated string.

Parameters:: title : str (mandatory)

the string to format.
Returns:: out : str

the formated string.

write_api_docs(indent=4)[source]¶

Generate API reST files.

Parameters:: indent : int

The number of blank prefix.

write_documentation_index()[source]¶: Generate the documentation index.

write_from_template(out_file, template_file, template_info)[source]¶

Edit/save a template file.

Parameters:

out_file : str

the location where the edited template file content is written.

template_file : str

the location of the template file.

template_info : dict

a mapping used to edit the template content.

write_gallery()[source]¶: Copy the example folder in the package to be documentated.

write_index()[source]¶: Generate the index page.

write_installation(pypi_index=None)[source]¶

Generate the installation recommendations.

Parameters:: pypi_index : str default None

set the pypi index of the module: useful if different from the module name.

write_layout()[source]¶: Generate the Sphinx layout.

write_search()[source]¶: Generate the search page.

write_sphinx_config()[source]¶: Generate the Sphinx configuration.