module helpgen.utils_sphinx_doc_helpers

Short summary

module pyquickhelper.helpgen.utils_sphinx_doc_helpers

Various variables and classes used to produce a Sphinx documentation.

source on GitHub

Classes

class	truncated documentation
IndexInformation	Keeps some information to index.
ModuleMemberDoc	Represents a member in a module. See inspect. Attributes:
RstFileHelp	Defines what a rst file and what it describes.

Functions

function	truncated documentation
compute_truncated_documentation	Produces a truncated version of a docstring.
example_function_latex	This function only contains an example with latex to check it is working fine.
fix_image_page_for_root	Looks for images and fix their path as if the extract were copied to the root.
get_module_objects	Gets all the classes from a module.
import_module	Imports a module using its filename.
make_label_index	Builds a sphinx label from a string by removing any odd characters.
process_look_for_tag	Looks for specific information in all files, collect them into one single page.
process_var_tag	Processes a docstring using tag @ var, and return a list of 2-tuple
remove_some_indent	Brings text to the left.

Properties

property	truncated documentation
classname	Returns the class name if the object is a method.
key	Returns a key to identify it.
truncdoc	Returns self.text.

Static Methods

staticmethod	truncated documentation
get_label	Returns a new label given the existing ones.

Methods

method	truncated documentation
__cmp__	Comparison operators, compares first the first, second the name (lower case).
__eq__	Operator ==.
__gt__	Operator >.
__init__
__init__
__init__
__lt__	Operator <.
__str__	usual
__str__	usual
add_label_if_not_present	The function checks the label is present in the original file.
add_prefix	Adds a prefix (for the documentation).
populate	Extracts some information about an object.
rst_link	return a link rst
rst_link	Returns a sphinx link on the object.
set_rst_file	Sets the rst file and checks the label is present in it.

Documentation

Various variables and classes used to produce a Sphinx documentation.

source on GitHub

class pyquickhelper.helpgen.utils_sphinx_doc_helpers.IndexInformation(type, label, name, text, rstfile, fullname)

Bases: object

Keeps some information to index.

source on GitHub

Parameters

• type – each type gets an index

• label – label used to index

• name – name to display

• text – text to show as a short description

• rstfile – tells which file the index refers to (rst file)

• fullname – fullname of a file the rst file describes

source on GitHub

__init__(type, label, name, text, rstfile, fullname)

Parameters

• type – each type gets an index

• label – label used to index

• name – name to display

• text – text to show as a short description

• rstfile – tells which file the index refers to (rst file)

• fullname – fullname of a file the rst file describes

source on GitHub

__str__()

usual

source on GitHub

add_label_if_not_present()

The function checks the label is present in the original file.

source on GitHub

static get_label(existing, suggestion)

Returns a new label given the existing ones.

Parameters

• existing – existing labels stored in a dictionary

• suggestion – the suggestion will be chosen if it does not exists, suggestion + zzz otherwise

Returns

string

source on GitHub

rst_link()

return a link rst

Returns

rst link

source on GitHub

set_rst_file(rstfile)

Sets the rst file and checks the label is present in it.

Parameters

rstfile – rst file

source on GitHub

property truncdoc

Returns self.text.

source on GitHub

class pyquickhelper.helpgen.utils_sphinx_doc_helpers.ModuleMemberDoc(obj, ty=None, cl=None, name=None, module=None)

Bases: object

Represents a member in a module.

See inspect.

Attributes:

• obj (object): object

• type (str): type

• cl (object): class it belongs to

• name (str): name

• module (str): module name

• doc (str): documentation

• truncdoc (str): truncated documentation

• owner (object): module

source on GitHub

Parameters

• obj – any kind of object

• ty – type (if you want to overwrite what the class will choose), this type is a string (class, method, function)

• cl – if is a method, class it belongs to

• name – name of the object

• module – module name if belongs to

source on GitHub

__cmp__(oth)

Comparison operators, compares first the first, second the name (lower case).

Parameters

oth – other object

Returns

-1, 0 or 1

source on GitHub

__eq__(oth)

Operator ==.

source on GitHub

__gt__(oth)

Operator >.

source on GitHub

__hash__ = None

__init__(obj, ty=None, cl=None, name=None, module=None)

Parameters

• obj – any kind of object

• ty – type (if you want to overwrite what the class will choose), this type is a string (class, method, function)

• cl – if is a method, class it belongs to

• name – name of the object

• module – module name if belongs to

source on GitHub

__lt__(oth)

Operator <.

source on GitHub

__str__()

usual

source on GitHub

add_prefix(prefix)

Adds a prefix (for the documentation).

Parameters

prefix – string

source on GitHub

property classname

Returns the class name if the object is a method.

Returns

class object

source on GitHub

property key

Returns a key to identify it.

source on GitHub

populate()

Extracts some information about an object.

source on GitHub

rst_link(prefix=None, class_in_bracket=True)

Returns a sphinx link on the object.

Parameters

• prefix – to correct the path with a prefix

• class_in_bracket – if True, adds the class in bracket for methods and properties

Returns

a string style, see below

String style:

:%s:`%s <%s>`               or
:%s:`%s <%s>` (class)

source on GitHub

class pyquickhelper.helpgen.utils_sphinx_doc_helpers.RstFileHelp(file, rst, doc)

Bases: object

Defines what a rst file and what it describes.

source on GitHub

Parameters

• file – original filename

• rst – produced rst file

• doc – documentation if any

source on GitHub

__init__(file, rst, doc)

Parameters

• file – original filename

• rst – produced rst file

• doc – documentation if any

source on GitHub

pyquickhelper.helpgen.utils_sphinx_doc_helpers._length_truncated_doc = 120

max length for short summaries

pyquickhelper.helpgen.utils_sphinx_doc_helpers.add_file_rst_template = '\n__FULLNAME_UNDERLINED__\n\n\n\n\n.. inheritance-diagram:: __FULLNAMENOEXT__\n\n\nShort summary\n+++++++++++++\n\n__DOCUMENTATION__\n\n\n__CLASSES__\n\n__FUNCTIONS__\n\n__PROPERTIES__\n\n__STATICMETHODS__\n\n__METHODS__\n\nDocumentation\n+++++++++++++\n\n.. automodule:: __FULLNAMENOEXT__\n    :members:\n    :special-members: __init__\n    :show-inheritance:\n\n__ADDEDMEMBERS__\n\n'

template for a module, substring __...__ ought to be replaced

pyquickhelper.helpgen.utils_sphinx_doc_helpers.add_file_rst_template_cor = {'class': '__CLASSES__', 'function': '__FUNCTIONS__', 'method': '__METHODS__', 'property': '__PROPERTIES__', 'staticmethod': '__STATICMETHODS__'}

fields to be replaced

pyquickhelper.helpgen.utils_sphinx_doc_helpers.add_file_rst_template_title = {'class': 'Classes', 'function': 'Functions', 'method': 'Methods', 'property': 'Properties', 'staticmethod': 'Static Methods'}

names for python objects

pyquickhelper.helpgen.utils_sphinx_doc_helpers.compute_truncated_documentation(doc, length=120, raise_exception=False)

Produces a truncated version of a docstring.

Parameters

• doc – doc string

• length – approximated length of the truncated docstring

• raise_exception – raises an exception when the result is empty and the input is not

Returns

truncated doc string

source on GitHub

pyquickhelper.helpgen.utils_sphinx_doc_helpers.example_function_latex()

This function only contains an example with latex to check it is working fine.

How to display a formula

We want to check this formula to successfully converted.

Brackets and backslashes might be an issue.

source on GitHub

pyquickhelper.helpgen.utils_sphinx_doc_helpers.fix_image_page_for_root(content, file)

Looks for images and fix their path as if the extract were copied to the root.

Parameters

• content – extracted content

• file – file where is comes from (unused)

Returns

content

source on GitHub

pyquickhelper.helpgen.utils_sphinx_doc_helpers.get_module_objects(mod)

Gets all the classes from a module.

Parameters

mod – module objects

Returns

list of ModuleMemberDoc

source on GitHub

pyquickhelper.helpgen.utils_sphinx_doc_helpers.import_module(rootm, filename, log_function, additional_sys_path=None, first_try=True)

Imports a module using its filename.

Parameters

• rootm – root of the module (for relative import)

• filename – file name of the module

• log_function – logging function

• additional_sys_path – additional path to include to sys.path before importing a module (will be removed afterwards)

• first_try – first call to the function (to avoid infinite loop)

Returns

module object, prefix

The function can also import compiled modules.

Warning

It adds the file path at the first position in sys.path and then deletes it.

source on GitHub

pyquickhelper.helpgen.utils_sphinx_doc_helpers.make_label_index(title, comment)

Builds a sphinx label from a string by removing any odd characters.

Parameters

• title – title

• comment – add this string in the exception when it raises one

Returns

label

source on GitHub

pyquickhelper.helpgen.utils_sphinx_doc_helpers.process_look_for_tag(tag, title, files)

Looks for specific information in all files, collect them into one single page.

Parameters

• tag – tag

• title – title of the page

• files – list of files to look for

Returns

a list of tuple (page, content of the page)

The function is looking for regular expression:

.. tag(...).
...
.. endtag.

They can be split into several pages:

.. tag(page::...).
...
.. endtag.

If the extracted example contains an image (..image:: ../../), the path is fixed too.

The function parses the files instead of loading the files as a module. The function needs to replace \\ by \, it does not takes into acount doc string starting with r'''. The function calls remove_some_indent with backslash=True to replace double backslashes by simple backslashes.

source on GitHub

pyquickhelper.helpgen.utils_sphinx_doc_helpers.process_var_tag(docstring, rst_replace=False, header=None)

Processes a docstring using tag @ var, and return a list of 2-tuple:

@ var    filename        file name
@ var    utf8            decode in utf8?
@ var    errors          decoding in utf8 can raise some errors

Parameters

• docstring – string

• rst_replace – if True, replace the var bloc var a rst bloc

• header – header for the table, if None, ["attribute", "meaning"]

Returns

a matrix with two columns or a string if rst_replace is True

source on GitHub

pyquickhelper.helpgen.utils_sphinx_doc_helpers.remove_some_indent(s, backslash=False)

Brings text to the left.

Parameters

• s – text

• backslash – if True, replace double backslash by simple backslash

Returns

text

source on GitHub