RSS blog page - 1/3 ==> Blog automation (4) documentation (8) example (2) latex (2) notebook (4) sphinx (10)

blog page - 1/3

Make a reference to a blog post

2016-06-11

Make a reference to the label label-to-this-blogpost to reference this blog post. Look at the source of this page to see how this id was specified.

post

Sphinx extensions in pyquickhelper

2016-04-04

Sphinx extensions implemented were move to a dedicated subfolder sphinxext:

post

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

read_csv and zip files

2016-02-06

read_csv is no longer able to extract a dataframe from a zip file. The parameter format changed for compression but the zip format disappeared from the list. I assume the reason is that zip files can contains many files.

pyquickhelper now implements the function read_csv which can extract all dataframe in a zip file or falls back into the regular function if no zip format is detected. In that case, it returns a dictionary of dataframes indexed by their name in the zip file.

from pyquickhelper.pandashelper import read_csv
dfs = read_csv("url_or_filename.zip", compression="zip")
print(dfs["dataframe.txt"].head())

If only one file must be converted as a dataframe, the parameter fvalid must be used:

from pyquickhelper.pandashelper import read_csv
dfs = read_csv("url_or_filename.zip", compression="zip",
               fvalid=lambda name: name == "the_file.txt")
print(dfs["the_file.txt"].head())

The others files will be loaded as text. In more details, when it is a zip file, the function reads a dataframe from a zip file by doing:

import io, zipfile, pandas

def read_zip(local_file, encoding="utf8"):

    with open(local_file, "rb") as local_file:
        content = local_file.read()

    dfs = {}
    with zipfile.ZipFile(io.BytesIO(content)) as myzip:
        infos = myzip.infolist()

        for info in infos:
            name = info.filename
            with myzip.open(name, "r") as f:
                text = f.read()

            text = text.decode(encoding="utf8")
            st = io.StringIO(text)
            df = pandas.read_csv(st, compression=compression, **params)
            dfs[name] = df

    return dfs

post

Badge for coverage

2016-01-01

pyquickhelper is using coverage to measure the coverage of the unit tests. coveralls cannot ingest these reports when codecov does with a simple command line such as:

codecov --token=69193a28-dc79-4a24-98ed-aedf441a8249
        --file=D:\jenkins\pymy\_pyquickhelper\_doc\sphinxdoc\source\coverage\coverage_report.xml
        --commit=f30c095f5da096e5db2ba6e5e0f7e07e833a8c81

It is provided by module codecov (or github/codecov). The coverage report is also available at pyquickhelper coverage. but these kinds of website keep track of the changes. Others available websites which provide badges are mentioned on the main page pyquickhelper.

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:

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

RSS blog page - 1/3 ==> 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)