tools_doc_sphinx.auto_doc_api

Summary

Script for automatic generation of API reference indexes (RST files), it must be launched before generating Sphinx documentation

Data

tools_doc_sphinx.auto_doc_api.path

Built-in mutable sequence.

Functions

tools_doc_sphinx.auto_doc_api.append_main_index_file(…)	Appends main RST index file of the documentation (which contains the doctree of the whole documentation) with the main RST index file of the API reference
tools_doc_sphinx.auto_doc_api.generate_index_files(…)	Main function for writing RST index files of a package/module and all sub-packages/modules
tools_doc_sphinx.auto_doc_api.generate_index_files_recursive(…)	Recursive function for writing RST index files of a (sub-)package/module and all sub-packages/modules
tools_doc_sphinx.auto_doc_api.get_members_defined_in_module(…)	Get members that are defined in a module (imported members are ignored)
tools_doc_sphinx.auto_doc_api.write_api_classes(…)	Writes “Classes” section
tools_doc_sphinx.auto_doc_api.write_api_data(…)	Writes “Data” section
tools_doc_sphinx.auto_doc_api.write_api_functions(…)	Writes “Functions” section
tools_doc_sphinx.auto_doc_api.write_autoclass_directive(…)	Writes autoclass directive in RST index file
tools_doc_sphinx.auto_doc_api.write_autodata_directive(…)	Writes autodata directive in RST index file for a set of data inside the same module
tools_doc_sphinx.auto_doc_api.write_autofunction_directive(…)	Writes autofunction directive in RST index file for a set of functions inside the same module
tools_doc_sphinx.auto_doc_api.write_automember(…)	Writes member inside autosummary directive in RST index file
tools_doc_sphinx.auto_doc_api.write_automodule_directive(…)	Writes automodule directive in RST index file
tools_doc_sphinx.auto_doc_api.write_autosummary_directive(…)	Writes autosummary directive in RST index file
tools_doc_sphinx.auto_doc_api.write_module_index(…)	Writes API page of a module
tools_doc_sphinx.auto_doc_api.write_module_summary(…)	Writes summary of a module for a specific type of member in RST index file
tools_doc_sphinx.auto_doc_api.write_package_index(…)	Writes all RST index files of a package
tools_doc_sphinx.auto_doc_api.write_section(…)	Writes a section in a RST index file
tools_doc_sphinx.auto_doc_api.write_toc_tree_directive(…)	Writes directive for table of content in RST index file
tools_doc_sphinx.auto_doc_api.write_toc_tree_index(…)	Writes index inside a table of content in RST index file

API

Data

tools_doc_sphinx.auto_doc_api.path = ['/home/docs/checkouts/readthedocs.org/user_builds/tools-doc-sphinx/checkouts/stable', '/home/docs/checkouts/readthedocs.org/user_builds/tools-doc-sphinx/checkouts/stable/doc/source', '/home/docs/checkouts/readthedocs.org/user_builds/tools-doc-sphinx/checkouts/stable/doc/source', '/home/docs/checkouts/readthedocs.org/user_builds/tools-doc-sphinx/envs/stable/lib/python37.zip', '/home/docs/checkouts/readthedocs.org/user_builds/tools-doc-sphinx/envs/stable/lib/python3.7', '/home/docs/checkouts/readthedocs.org/user_builds/tools-doc-sphinx/envs/stable/lib/python3.7/lib-dynload', '/home/docs/.pyenv/versions/3.7.9/lib/python3.7', '/home/docs/checkouts/readthedocs.org/user_builds/tools-doc-sphinx/envs/stable/lib/python3.7/site-packages']

Built-in mutable sequence.

If no argument is given, the constructor creates a new empty list. The argument must be an iterable if specified.

Functions

tools_doc_sphinx.auto_doc_api.append_main_index_file(main_index_path, api_ref_name)

Appends main RST index file of the documentation (which contains the doctree of the whole documentation) with the main RST index file of the API reference

Parameters

• main_index_path (str) – path to the main RST index file of the documentation

• api_ref_name (str) – name of the directory containing the RST index files of the API reference

tools_doc_sphinx.auto_doc_api.generate_index_files(package_name, doc_dir, package_dir=None, output_name='APIreference', chapter_title='API reference', flag_include_main=False)

Main function for writing RST index files of a package/module and all sub-packages/modules

First, it creates the output directory and the RST index file at the first level of the package. Then, it creates the directories corresponding to the package structure and the RST index files thanks to the recursive function generate_index_files_recursive().

Parameters

• package_name (str) – name of the package/module

• doc_dir (str) – directory where is stored the documentation source

• package_dir (str) – directory where is stored the package (to be temporally added in the PYTHONPATH)

• output_name (str) – name of the directory to create inside doc_dir, where to store RST index files

• chapter_title (str) – name of the chapter inside the whole documentation

• flag_include_main (bool) – specify if the executable module __main__.py must be included in the documentation

tools_doc_sphinx.auto_doc_api.generate_index_files_recursive(package_name, package_root_name, out_dir)

Recursive function for writing RST index files of a (sub-)package/module and all sub-packages/modules

The function importlib.import_module() is used to import the package/module, see https://docs.python.org/3/library/importlib.html#importlib.import_module

Parameters

• package_name (str) – name of the package, first positional argument of importlib.import_module()

• package_root_name (str) – root of the package/module to import, keyword argument of importlib.import_module()

• out_dir (str) – directory where to save the RST index files

tools_doc_sphinx.auto_doc_api.get_members_defined_in_module(module, condition_function)

Get members that are defined in a module (imported members are ignored)

Parameters

• module – imported module

• condition_function – may be any ‘isXXX’ function of the module inspect, None (get everything) or ‘’ (get global variables), see https://docs.python.org/3/library/inspect.html

Returns

list of members

Return type

list

tools_doc_sphinx.auto_doc_api.write_api_classes(index_path, module_full_name, class_list)

Writes “Classes” section

Parameters

• index_path (str) – path to the RST file

• module_full_name (str) – full name of the module inside the package

• class_list (list) – list of the classes inside the module

tools_doc_sphinx.auto_doc_api.write_api_data(index_path, module_full_name, data_list)

Writes “Data” section

Parameters

• index_path (str) – path to the RST file

• module_full_name (str) – full name of the module inside the package

• data_list (list) – list of the data inside the module

tools_doc_sphinx.auto_doc_api.write_api_functions(index_path, module_full_name, func_list)

Writes “Functions” section

Parameters

• index_path (str) – path to the RST file

• module_full_name (str) – full name of the module inside the package

• func_list (list) – list of the functions inside the module

tools_doc_sphinx.auto_doc_api.write_autoclass_directive(index_path, class_full_name)

Writes autoclass directive in RST index file

Parameters

• index_path (str) – path to the RST file

• class_full_name (str) – full name of the class inside the package

tools_doc_sphinx.auto_doc_api.write_autodata_directive(index_path, module_full_name, data_list)

Writes autodata directive in RST index file for a set of data inside the same module

Parameters

• index_path (str) – path to the RST file

• module_full_name (str) – full name of the module inside the package

• data_list (list) – list of data name inside the module

tools_doc_sphinx.auto_doc_api.write_autofunction_directive(index_path, module_full_name, func_list)

Writes autofunction directive in RST index file for a set of functions inside the same module

Parameters

• index_path (str) – path to the RST file

• module_full_name (str) – full name of the module inside the package

• func_list (list) – list of functions name inside the module

tools_doc_sphinx.auto_doc_api.write_automember(index_path, member_full_name)

Writes member inside autosummary directive in RST index file

Parameters

• index_path (str) – path to the RST file

• member_full_name (str) – full name of the member inside the package

tools_doc_sphinx.auto_doc_api.write_automodule_directive(index_path, module_full_name)

Writes automodule directive in RST index file

Parameters

• index_path (str) – path to the RST file

• module_full_name (str) – full name of the module inside the package

tools_doc_sphinx.auto_doc_api.write_autosummary_directive(index_path)

Writes autosummary directive in RST index file

Parameters

index_path (str) – path to the RST file

tools_doc_sphinx.auto_doc_api.write_module_index(index_path, module, module_full_name)

Writes API page of a module

Parameters

• index_path (str) – path to the RST file

• module – imported module

• module_full_name (str) – full name of the module inside the package

tools_doc_sphinx.auto_doc_api.write_module_summary(index_path, module_full_name, member_list, member_type)

Writes summary of a module for a specific type of member in RST index file

Parameters

• index_path (str) – path to the RST file

• module_full_name (str) – full name of the module inside the package

• member_list (list) – list of the members inside the module (all elements are of same type)

• member_type (str) – members type (classes, functions, data, …)

tools_doc_sphinx.auto_doc_api.write_package_index(index_path, package, package_full_name, out_dir)

Writes all RST index files of a package

Parameters

• index_path (str) – path to the RST file

• package – imported package

• package_full_name (str) – full name of the package

• out_dir (str) – directory where to save RST index files

tools_doc_sphinx.auto_doc_api.write_section(index_path, title, level=0, file_option='a')

Writes a section in a RST index file

Parameters

• index_path (str) – path to the RST file

• title (str) – section title

• level (int) – section level (0 page title, 1 section, 2 subsection, 3 subsubsection)

• file_option (str) – mode when opening the RST file

tools_doc_sphinx.auto_doc_api.write_toc_tree_directive(index_path)

Writes directive for table of content in RST index file

Parameters

index_path (str) – path to the RST file

tools_doc_sphinx.auto_doc_api.write_toc_tree_index(index_path, index_link)

Writes index inside a table of content in RST index file

Parameters

• index_path (str) – path to the RST file

• index_link (str) – name of the folder containing the index file to point to