XD blog

blog page

sphinx

2017-07-02 Include output of a script in the Python documentation

The directive runpython runs a python script and insert the output in the documentation. 

.. runpython::
    
    import sys
    print(sys.version_info)

Every printed information is added to the documntation : 

sys.version_info(major=3, minor=6, micro=1, releaselevel='final', serial=0)

Two intersections options :

One extension must be added to configuration conf.py: 

    extensions = ['sphinx.ext.intersphinx',
        ...
        'pyquickhelper.sphinxext.sphinx_runpython_extension']

One example (in French) : demo runpython. The second one shows how I use to build content (still French): rendering and source.

2016-06-25 Writing scientific with Sphinx

There exists many cheat sheets for Sphinx. One of the most simple and useful is the following: Sample Document. Just click on the source.

Sometimes line-block does not keep indentation. The solution is then to update your style as follows: my-style.css.

2015-06-07 Custom Directive on Sphinx

I recently discovered a nice way to integrate plots in sphinx documentation with the custom directive bokeh-plot. I thought it would be quite easy to create mine to add a simple blogging system. However the documentation is pretty rare on that topic. All my searches ended up at Tutorial: Writing a simple extension. So here are my finding about creating a custom directive BlogPostDirective to process something like: 

.. blogpost::
    :title: Migration to IPython 3.1
    :keywords: ipython, migration, jupyter, jenkins, pandoc
    :date: 2015-04-16
    :categories: ipython, documentation
    
    Any text this blog could contains and any RST tag::
    
        ...

more...

2015-04-18 A few modules for Sphinx

Here are a few modules I will probably use when I need them to generate documentation with Sphinx. This is just to avoid searching for them again.

And some others modules to easily build graphs with javascript and python:

2015-04-06 Blog generator

I publish my teaching material as python module. I added some tricks to made that happen. Recently, I was wondering how to add some kind of blog posts inside the documentation. As I have several teaching going on, I did not want to merge all blog posts into a single one where students would have to filter out what blog post is meant for them. So I thought about using a kind of blog generator written in Python on the top of Sphinx. I went through that blog post What's the best available static blog/website generator in Python? which gives a short list of them. It is possible to check their popularity by looking at Top Open-Source Static Site Generators.

I wanted to follow the same design for my blog, same pattern. So I was looking for a tool generated RST files and not directly HTML. Tinkerer seemed a good choice. Should I have to add the message powered by Tinkerer as every site using it is displaying that sentance? I also looked into Pelican, nykola. I also found a very simple one with a French name: éClaircie.

I finally decided to write some code to process my own blog posts and to insert them in the documentation of a an existing python module. It is not finalized yet but it looks like that: An example of a blog post included in the documentation. This process forces me to dig into sphinx devext API which I do not fully understand yet. It is quite difficult to find good examples on the web. What I have implemented is available here: pyquickhelper.helpgen.

By implementing my own blog, I cannot have all the features the static generators have (good templating, many languages). I spent most of my time in implementing the blog post aggregations (categories, months) and the splitting (not more than 10 blog posts per pages). But now, if I want to customize Sphinx a little bit, it is easier.

2014-10-30 Issue with some Sphinx themes and Internet Explorer

The theme Bootstrap does not work well on Internet Explorer. In that case, the file [python_path]/Lib/site-packages/sphinx/themes/basic/layout.html must be modified to include the following line: 

<meta http-equiv="X-UA-Compatible" content="IE=edge" />

2014-04-13 Latex formulas with Sphinx

Is it worth writing about something which took me 15 minutes to find out and others 15 to try? And it will be another 10 to write it down... I wonder! Anyway, I was looking for a way to add formulas in my python documentation.


more...

2014-02-01 Sphinx themes and presentation

A year ago, I was looking for tools to generate automated help for a Python module. However, I was looking a tool able to use the javadoc style because most of my old code uses it. Doxygen is nice but the unavoidable tool is now Sphinx (+ autodoc). I will not explain what I did because I did it quick (and wrong). The right way to do it is to use the following Sphinx extension: Breathe. Anyway, I do not remember all the issues I had when trying Sphinx but I found the documentation more usable. So I played a little with some theme I was able to find:

Another thing I did wrong is the way I made the design of this blog. I implemented many thing (keywords generation, month aggregation...). But today, I would try first to look at Pelican or even directly use Sphinx which already does many things about indexes. If you look on the internet about sphinx blog theme, you would find some examples like the following one: Tinkerer. You can even find theme to do presentation (instead of PowerPoint I suppose):


more...

2013-06-13 A template to create a Python module including Sphinx documentation and a setup

My students often struggle to debug their programs when two or three students need to synchronize their versions. A good way to avoid wasting too much time is to use a tool to keep track of the modifications such as github. It then becomes easy to synchronize multiple versions.

However, students still need to debug the program after a synchronization. A good practice is to write unit tests. Every time, you write a complex function or an easy one, a unit test should be written to ensure its behaviour will not change after many changes. But it means to add a file, to spend some time to do it right, and to frequently run all the unit tests. This is usually too painful when the project will only last a couple of months. Plus, you usually commit yourself to do it only after you went through the nightmare of debugging once.

Last but not least, my students usually do not add documentation to their code. Most of the time, they do not need it because the project is too short to lose track of the modifications and too small to not know it completely. Maybe another reason is because they cannot see a compiled version of the documentation. The best way is to use Sphinx ut using it means spending a couple of hours at least (a lot of more if you do it for the first time). Documentation can also be used to navigate through the program.

For those reasons, I made a kind of template for a Python module. It includes an easy mechanism to add a unit test and to run it. It generates with the documentation with no change and it also generated a setup (gz, exe) with no change either. You can get it here: Pieces of codes, libraries (section Code). After you downloaded it, a page gives the short list of instructions to tweak the template in order to make it yours: README.

Xavier Dupré