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

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

Changed in version 1.8: Disables latex if 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)[source][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 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

Changed in version 1.8: Markdown format was added.

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, load_bokeh=False, **options)[source][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

  • load_bokeh – load bokeh extensions, disabled by default as it takes a few seconds

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

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.

Changed in version 1.8: New nodes are now optional in directives. Markdown format was added. Parameters ret_doctree, load_bokeh were added.

source on GitHub

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

Converts a RST string into simplified RST.

Parameters
  • rststringrst 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