2015-12 - 1/1 Blog automation (4) documentation (8) example (2) latex (2) notebook (4) sphinx (10)

2015-12 - 1/1¶

Sphinx extensions¶

2015-12-12

The following repository birkenfeld/sphinx-contrib/ contains many useful extensions to improve the rendering of Sphinx documentation:

imagesvg: to include svg figures
jsdemo: to demo javascript and HTML

Demo

Source

<button>Click me!</button>

The following extension replaces the search bar by an entry which mimicks autocompletion by showing results as the user is typing:

lunrsearch

Their are now part of the default configuration proposed by this module. See set_sphinx_variables.

post

Python code to generate part of sphinx documentation¶

2015-12-12

I used the same title as a question asked on stackoverflow: Python code to generate part of sphinx documentation, is it possible?. It became the following RunPythonDirective which does the same with more options:

.. runpython:
    :showcode:
    :rst:

    from pyquickhelper import df2rst
    import pandas
    df = <some dataframe>
    print(df2rst(df))

Because of the option rst, what is printed out becomes part of the documentation through function nested_parse_with_titles. In sphinx configuration setup, the following lines must be added:

from pyquickhelper.helpgen.sphinx_runpython_extension import RunPythonDirective
from pyquickhelper.helpgen.sphinx_runpython_extension import runpython_node, visit_runpython_node, depart_runpython_node

def setup(app):
    app.add_node(runpython_node,
                 html=(visit_runpython_node, depart_runpython_node),
                 latex=(visit_runpython_node, depart_runpython_node),
                 text=(visit_runpython_node, depart_runpython_node))
    app.add_directive('runpython', RunPythonDirective)

post

Local contents in Sphinx¶

2015-12-05

The Sphinx command contents adds a table of contents to a page. As contents is pretty common, on the web, it is not always easy to search for it:

.. contents::
    :local:

An example can be found here.

post

2015-12 - 1/1 2015-04 (8) 2015-05 (4) 2015-08 (2) 2015-10 (1) 2015-12 (3) 2016-01 (1) 2016-02 (3) 2016-04 (1) 2016-06 (1)