module helpgen.rst_converters
¶
Short summary¶
module pyquickhelper.helpgen.rst_converters
Helpers to convert docstring to various format.
Functions¶
function |
truncated documentation |
---|---|
Tries to improve the indentation before running docutils. |
|
Defines or overrides default options for Sphinx, listed below. |
|
Converts a docstring into a HTML format. |
|
Converts a string from RST into HTML format or transformed RST. |
|
Documentation¶
Helpers to convert docstring to various format.
- pyquickhelper.helpgen.rst_converters.correct_indentation(text)[source]¶
Tries to improve the indentation before running docutils.
- Parameters:
text – text to correct
- Returns:
corrected text
- pyquickhelper.helpgen.rst_converters.default_sphinx_options(fLOG=<function noLOG>, **options)[source]¶
Defines or overrides default options for Sphinx, listed below.
blocref_link_only = False blog_background = False faqref_link_only = False graphviz_dot = dot graphviz_output_format = png imgmath_dvipng = dvipng imgmath_dvisvgm = dvisvgm imgmath_image_format = png imgmath_latex = latex language = en math_number_all = False mathdef_link_only = True nbref_link_only = False out_blogpostlist = [] out_runpythonlist = [] sharepost = None todo_link_only = False todoext_link_only = False
- pyquickhelper.helpgen.rst_converters.docstring2html(function_or_string, format='html', fLOG=<function noLOG>, writer='html', keep_warnings=False, directives=None, language='en', layout='docutils', document_name='<<string>>', filter_nodes=None, **options)[source]¶
Converts a docstring into a HTML format.
- Parameters:
function_or_string – function, class, method or doctring
format – output format (
'html'
or ‘rawhtml
’)fLOG – logging function
writer –
'html'
for HTML format,'rst'
for RST format,'md'
for MD formatkeep_warnings – keep_warnings in the final HTML
directives – new directives to add (see below)
language – language
layout –
'docutils'
,'sphinx'
,'sphinx_body'
, see below.document_name – document_name for this string
filter_nodes – transform the doctree before writing the results (layout must be ‘sphinx’)
options – Sphinx options see Render math as images, a subset of options is used, see
default_sphinx_options
. By default, the theme (option html_theme) will'basic'
.
- Returns:
(str) HTML format or (IPython.core.display.HTML)
Produce HTML documentation for a function or class
The following code can display the dosstring in HTML format to display it in a notebook.
from pyquickhelper.helpgen import docstring2html import sklearn.linear_model docstring2html(sklearn.linear_model.LogisticRegression)
The output format is defined by:
- pyquickhelper.helpgen.rst_converters.rst2html(s, fLOG=<function noLOG>, writer='html', keep_warnings=False, directives=None, language='en', layout='docutils', document_name='<<string>>', external_docnames=None, filter_nodes=None, new_extensions=None, update_builder=None, ret_doctree=False, destination=None, destination_path=None, **options)[source]¶
Converts a string from RST into HTML format or transformed RST.
- Parameters:
s – string to convert
fLOG – logging function (warnings will be logged)
writer –
'html'
for HTML format,'rst'
for RST format,'md'
for MD format,'elatex'
for latex format,'doctree'
to get the doctree, writer can also be a tuple for custom formats and must be like('buider_name', builder_class)
.keep_warnings – keep_warnings in the final HTML
directives – new directives to add (see below)
language – language
layout –
'docutils'
,'sphinx'
,'sphinx_body'
, see below.document_name – document name, not really important since the input is a string
external_docnames – if the string to parse makes references to other documents, if one is missing, an exception is raised.
filter_nodes – transforms the doctree before writing the results (layout must be ‘sphinx’), the function takes a doctree as a single parameter
new_extensions – additional extension to setup
update_builder – update the builder after it is instantiated
ret_doctree – returns the doctree
destination – set a destination (requires for some extension)
destination_path – set a destination path (requires for some extension)
options – Sphinx options see Render math as images, a subset of options is used, see
default_sphinx_options
. By default, the theme (option html_theme) will'basic'
.
- Returns:
HTML format
directives is None or a list of 2 or 5-uple:
a directive name (mandatory)
a directive class: see Sphinx Directive, see also
RunPythonDirective
as an example (mandatory)a docutils node: see
runpython_node
as an exampletwo functions: see
visit_runpython_node
,depart_runpython_node()
as an example
The parameter layout specify the kind of HTML you need.
'docutils'
: very simple HTML, style is not included, recursive directives are not processed (recursive means they modify the doctree). The produced HTML only includes the body (no HTML header).'sphinx'
: in memory sphinx, the produced HTML includes the header, it is also recursive as directives can modify the doctree.'sphinx_body'
: same as'sphinx'
but only the body is returned.
If the writer is a tuple, it must be a 2-uple
(builder_name, builder_class)
. However, the builder class must contain an attribute_writer_class
with the associated writer. The builcer class must also implement a methoditer_pages
which enumerates all written pages:def iter_pages(self) -> Dict[str,str]
where the key is the document name and the value is its content.How to test a Sphinx directive?
The following code defines a simple directive definedbased on an existing one. It also defined what to do if a new node is inserted in the documentation.
from docutils import nodes from pyquickhelper.helpgen import rst2html class runpythonthis_node(nodes.Structural, nodes.Element): pass class RunPythonThisDirective (RunPythonDirective): runpython_class = runpythonthis_node def visit_node(self, node): self.body.append("<p><b>visit_node</b></p>") def depart_node(self, node): self.body.append("<p><b>depart_node</b></p>") content = ''' test a directive ================ .. runpythonthis:: print("this code shoud appear" + "___") '''.replace(" ", "") # to remove spaces at the beginning of the line tives = [ ("runpythonthis", RunPythonThisDirective, runpythonthis_node, visit_node, depart_node) ] html = rst2html(content, writer="html", keep_warnings=True, directives=tives)
Unfortunately, this functionality is only tested on Python 3. It might not work on Python 2.7. The function produces files if the document contains latex converted into image.
How to get more about latex errors?
Sphinx is not easy to use when it comes to debug latex expressions. I did not find an easy way to read the error returned by latex about a missing bracket or an unknown command. I finally added a short piece of code in
sphinx.ext.imgmath.py
just after the call to the executable indicated by imgmath_latexif b'...' in stdout or b'LaTeX Error' in stdout: print(self.builder.config.imgmath_latex_preamble) print(p.returncode) print("################") print(latex) print("..........") print(stdout.decode("ascii").replace("\r", "")) print("-----") print(stderr)
It displays the output if an error happened.
How to hide command line window while compiling latex?
Sphinx calls latex through command line. On Windows, a command line window can annoyingly show up anytime a formula is compiled. The following can be added to hide it:
startupinfo = STARTUPINFO() startupinfo.dwFlags |= STARTF_USESHOWWINDOW
And
, startupinfo=startupinfo
must be added to linesp = Popen(...
.By default, the function now interprets Sphinx directives and not only docutils ones. Parameter directives adds a directive before parsing the RST. The function is more consistent. Format
rst
is available as well as custom builders. New nodes are optional in directives. Markdown format was added.
- pyquickhelper.helpgen.rst_converters.rst2rst_folder(rststring, folder, document_name='index', **options)[source]¶
Converts a RST string into simplified RST.
- Parameters:
rststring – rst string
folder – the builder needs to write the resuts in a folder defined by this parameter
document_name – main document
options – additional options (same as conf.py)
- Returns:
converted string