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