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
Classes¶
class |
truncated documentation |
---|---|
Keeps some information to index. |
|
Represents a member in a module. See inspect. Attributes: |
|
Defines what a rst file and what it describes. |
Functions¶
function |
truncated documentation |
---|---|
Produces a truncated version of a docstring. |
|
This function only contains an example with latex to check it is working fine. |
|
Looks for images and fix their path as if the extract were copied to the root. |
|
Gets all the classes from a module. |
|
Imports a module using its filename. |
|
Builds a sphinx label from a string by removing any odd characters. |
|
Looks for specific information in all files, collect them into one single page. |
|
Processes a docstring using tag |
|
Brings text to the left. |
Properties¶
property |
truncated documentation |
---|---|
Returns the class name if the object is a method. |
|
Returns a key to identify it. |
|
Returns |
Static Methods¶
staticmethod |
truncated documentation |
---|---|
Returns a new label given the existing ones. |
Methods¶
method |
truncated documentation |
---|---|
Comparison operators, compares first the first, second the name (lower case). |
|
Operator |
|
Operator |
|
Operator |
|
usual |
|
usual |
|
The function checks the label is present in the original file. |
|
Adds a prefix (for the documentation). |
|
Extracts some information about an object. |
|
return a link rst |
|
Returns a sphinx link on the object. |
|
Sets the rst file and checks the label is present in it. |
Documentation¶
various variables and classes used to produce a Sphinx documentation
-
class
pyquickhelper.helpgen.utils_sphinx_doc_helpers.
IndexInformation
(type, label, name, text, rstfile, fullname)[source]¶ Bases:
object
Keeps some information to index.
- 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
-
__init__
(type, label, name, text, rstfile, fullname)[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
-
static
get_label
(existing, suggestion)[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
-
set_rst_file
(rstfile)[source]¶ Sets the rst file and checks the label is present in it.
- Parameters
rstfile – rst file
-
class
pyquickhelper.helpgen.utils_sphinx_doc_helpers.
ModuleMemberDoc
(obj, ty=None, cl=None, name=None, module=None)[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
- 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
-
__cmp__
(oth)[source]¶ Comparison operators, compares first the first, second the name (lower case).
- Parameters
oth – other object
- Returns
-1, 0 or 1
-
__init__
(obj, ty=None, cl=None, name=None, module=None)[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
-
rst_link
(prefix=None, class_in_bracket=True)[source]¶ 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)
-
class
pyquickhelper.helpgen.utils_sphinx_doc_helpers.
RstFileHelp
(file, rst, doc)[source]¶ Bases:
object
Defines what a rst file and what it describes.
- Parameters
file – original filename
rst – produced rst file
doc – documentation if any
-
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]¶ 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
-
pyquickhelper.helpgen.utils_sphinx_doc_helpers.
example_function_latex
()[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.
Brackets and backslashes might be an issue.
-
pyquickhelper.helpgen.utils_sphinx_doc_helpers.
fix_image_page_for_root
(content, file)[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
-
pyquickhelper.helpgen.utils_sphinx_doc_helpers.
get_module_objects
(mod)[source]¶ Gets all the classes from a module.
- Parameters
mod – module objects
- Returns
list of ModuleMemberDoc
-
pyquickhelper.helpgen.utils_sphinx_doc_helpers.
import_module
(rootm, filename, log_function, additional_sys_path=None, first_try=True)[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
The function can also import compiled modules.
Warning
It adds the file path at the first position in
sys.path
and then deletes it.
-
pyquickhelper.helpgen.utils_sphinx_doc_helpers.
make_label_index
(title, comment)[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
-
pyquickhelper.helpgen.utils_sphinx_doc_helpers.
process_look_for_tag
(tag, title, files)[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 withr'''
. The function callsremove_some_indent
withbackslash=True
to replace double backslashes by simple backslashes.
-
pyquickhelper.helpgen.utils_sphinx_doc_helpers.
process_var_tag
(docstring, rst_replace=False, header=None)[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