module helpgen.utils_sphinx_doc_helpers

Inheritance diagram of pyquickhelper.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)[source][source]

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)[source][source]
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__()[source][source]

usual

source on GitHub

add_label_if_not_present()[source][source]

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

source on GitHub

static get_label(existing, suggestion)[source][source]

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

return a link rst

Returns

rst link

source on GitHub

set_rst_file(rstfile)[source][source]

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

Parameters

rstfile – rst file

source on GitHub

truncdoc[source]

Returns self.text.

source on GitHub

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

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)[source][source]

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)[source][source]

Operator ==.

source on GitHub

__gt__(oth)[source][source]

Operator >.

source on GitHub

__hash__ = None[source]
__init__(obj, ty=None, cl=None, name=None, module=None)[source][source]
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)[source][source]

Operator <.

source on GitHub

__str__()[source][source]

usual

source on GitHub

add_prefix(prefix)[source][source]

Adds a prefix (for the documentation).

Parameters

prefix – string

source on GitHub

classname[source]

Returns the class name if the object is a method.

Returns

class object

source on GitHub

key[source]

Returns a key to identify it.

source on GitHub

populate()[source][source]

Extracts some information about an object.

source on GitHub

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)[source][source]

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)[source][source]
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[source]

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'[source]

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__'}[source]

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'}[source]

names for python objects

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

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()[source][source]

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.

\left \{ \begin{array}{l} \min_{x,y} \left \{ x^2 + y^2 - xy + y \right \}
\\ \text{sous contrainte} \; x + 2y = 1 \end{array}\right .

Brackets and backslashes might be an issue.

source on GitHub

pyquickhelper.helpgen.utils_sphinx_doc_helpers.fix_image_page_for_root(content, file)[source][source]

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)[source][source]

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)[source][source]

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

Warning

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

Changed in version 1.7: Add parameter first_try.

Changed in version 1.8: Can import compiled modules.

source on GitHub

pyquickhelper.helpgen.utils_sphinx_doc_helpers.make_label_index(title, comment)[source][source]

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)[source][source]

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)[source][source]

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)[source][source]

Brings text to the left.

Parameters
  • s – text

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

Returns

text

source on GitHub