module helpgen.rst_converters

Short summary

module pyquickhelper.helpgen.rst_converters

Helpers to convert docstring to various format.

source on GitHub

Functions

function	truncated documentation
correct_indentation	Tries to improve the indentation before running docutils.
default_sphinx_options	Defines or overrides default options for Sphinx, listed below.
docstring2html	Converts a docstring into a HTML format.
rst2html	Converts a string from RST into HTML format or transformed RST.
rst2rst_folder	Converts a RST string into simplified RST.

Documentation

Helpers to convert docstring to various format.

source on GitHub

pyquickhelper.helpgen.rst_converters.correct_indentation(text)

Tries to improve the indentation before running docutils.

Parameters:

text – text to correct

Returns:

corrected text

source on GitHub

pyquickhelper.helpgen.rst_converters.default_sphinx_options(fLOG=<function noLOG>, **options)

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

latex is not available on Windows.

source on GitHub

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)

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 format

• 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 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:

• 'html': IPython HTML object

• 'rawhtml': HTML as text + style

• 'rst': rst

• 'text': raw text

source on GitHub

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)

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 example

• two 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 method iter_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_latex

if 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 lines p = 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.

source on GitHub

pyquickhelper.helpgen.rst_converters.rst2rst_folder(rststring, folder, document_name='index', **options)

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

source on GitHub