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

sphinx - 1/1¶

Sphinx extensions in pyquickhelper¶

2016-04-04

Sphinx extensions implemented were move to a dedicated subfolder sphinxext:

Share buttons on a page from the documenation.¶

2016-02-14

pyquickhelper now includes a directive and a role to share a page from the documentation on networks. See ShareNetDirective and sharenet_role. The syntax is the following:

:sharenet:`twitter-facebook-linkedin-20`

The text must be different networks separated by -. The last integer indicates the size of the circles. If the buttons do not show up on the page, try to add -body:

:sharenet:`twitter-facebook-linkedin-20-body`

It specifies the javacript which draws the buttons is included on the HTML body and not in the header. The header section might be rewritten by other custom commands such as autodoc. The main javascript part is the following:

<script>
function share_url(share) {
    var url = share + encodeURIComponent(window.location.href);
    window.location.href = url;
}

function share_icon(divid, text) {
    var canvas = document.getElementById(divid);
    var context = canvas.getContext('2d');
    var centerX = canvas.width / 2;
    var centerY = canvas.height / 2;
    var radius = centerX;

    context.beginPath();
    context.arc(centerX, centerY, radius, 0, 2 * Math.PI, false);
    context.fillStyle = '#444444';
    context.fill();
    context.font = '' + (centerX*4/3) + 'pt Calibri';
    context.textAlign = 'center';
    context.fillStyle = '#FFFFFF';
    context.fillText(text, centerX, centerY+centerY*16/30);
}
</script>

Then to add a button to share on facebook:

<a href="#" onclick="share_url('https://www.facebook.com/sharer/sharer.php?u=');return false;"><canvas height="20" id="canvas-f" width="20"/></a>
<script>share_icon('canvas-f', 'f');</script>

On Linkedin:

<a href="#" onclick="share_url('https://www.linkedin.com/shareArticle?mini=true&amp;title=&amp;summary=&amp;source=&amp;url=');return false;"><canvas height="20" id="canvas-in" width="20"/></a>
<script>share_icon('canvas-in', 'in');</script>

On twitter:

<a href="#" onclick="share_url('https://twitter.com/home?status=');return false;"><canvas height="20" id="canvas-t" width="20"/></a>
<script>share_icon('canvas-t', 't');</script>

post

Bigger text in the documentation¶

2016-02-14

pyquickhelper now includes a role bigger which make a text bigger

:bigger:`bigger`

Or smaller

:bigger:`::1:smaller`

Or even bigger

:bigger:`::6:even bigger`

post

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

A few tips with Sphinx¶

2015-10-10

Sphinx generates many warning when it builds the documentation despite the fact the result looks good. Some cases.

nested bullets

According to How to create a nested list in reStructuredText?, a space must be inserted for nested bullets. The wrong syntax:

* level 1
    * level 2
    * level 2 as well
* level 1 again

The right syntax:

* level 1

    * level 2
    * level 2 as well

* level 1 again

latex formulas

The page Math support in Sphinx explains how to set up math environment (latex or mathjax). But if you add matplotlib to convert equations into images (matplotlib.sphinxext.mathmpl), the sphinx extension sphinx.ext.pngmath is disabled. Matplotlib extension has some limitations. \text does not work.

formulas in docstring

When included in a doc string, backslashes must be doubled:

"""
\\min_i \\{ ...
"""

post

Why do I see invered question in a notebook converted into PDF?¶

2015-08-30

The function process_notebooks still uses the executable pdflatex and not xetex which can handle inline unicode characters. That’s why they are replaced by ¿ by function post_process_latex.

post

Issue with module babel¶

2015-08-17

I went through the following issue with the latest version of babel (2.0). It happens when I try to generate the documentation for this module. It gave me the following exception:

  File "c:\python34_x64\lib\site-packages\sphinx\__init__.py", line 51, in main
    sys.exit(build_main(argv))
  File "c:\python34_x64\lib\site-packages\sphinx\__init__.py", line 61, in build_main
    from sphinx import cmdline
  File "c:\python34_x64\lib\site-packages\sphinx\cmdline.py", line 23, in <module>
    from sphinx.application import Sphinx
  File "c:\python34_x64\lib\site-packages\sphinx\application.py", line 37, in <module>
    from sphinx.builders import BUILTIN_BUILDERS
  File "c:\python34_x64\lib\site-packages\sphinx\builders\__init__.py", line 23, in <module>
    from sphinx.util import i18n, path_stabilize
  File "c:\python34_x64\lib\site-packages\sphinx\util\i18n.py", line 15, in <module>
    from babel.messages.pofile import read_po
  File "c:\python34_x64\lib\site-packages\babel\messages\__init__.py", line 12, in <module>
    from babel.messages.catalog import *
  File "c:\python34_x64\lib\site-packages\babel\messages\catalog.py", line 23, in <module>
    from babel.dates import format_datetime
  File "c:\python34_x64\lib\site-packages\babel\dates.py", line 28, in <module>
    from babel.util import UTC, LOCALTZ
  File "c:\python34_x64\lib\site-packages\babel\util.py", line 278, in <module>
    from babel import localtime
  File "c:\python34_x64\lib\site-packages\babel\localtime\__init__.py", line 21, in <module>
    from babel.localtime._win32 import _get_localzone
  File "c:\python34_x64\lib\site-packages\babel\localtime\_win32.py", line 18, in <module>
    tz_names = get_global('windows_zone_mapping')
  File "c:\python34_x64\lib\site-packages\babel\core.py", line 58, in get_global
    _global_data = pickle.load(fileobj)
TypeError: an integer is required (got type str)

The exception disappeared after I reverted to babel 1.3.

post

Anaconda does not have the latest version of Sphinx¶

2015-04-16

As of today, when I type conda update sphinx, The Anaconda distribution does not upgrade to 1.3 and I need it to get the extension sphinx.ext.napoleon. So I need to type pip install sphinx --upgrade instead.

post

sphinx - 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)