Sphinx themes and presentation

presentation, python, sphinx, theme

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

I tried the module sphinxjp.themes.revealjs. It is based on a javascript framework Reveal.js and has many nice examples. So, I installed the version for Sphinx from here (I had to make a fix) or you can execute the following line:

from pymyinstall import ModuleInstall
ModuleInstall("sphinxjp.themes.revealjs", "github", "sdpython").install(temp_folder="download")

Then, a new Sphinx project needs to be created by running the two following instructions from a command line window and in the folder where you want to create the presentation:

set path=%path%;c:\Python33;c:\Python33\Scripts
sphinx-quickstart

It requires to answer many easy questions. Once, it is done, you will have two folders source and build. To build the documentation/presentation, you just need to run:

make html

The presentation will start from build/html/index.html which should have been created. It is not the presentation we expect because we did not tell Sphinx to choose this theme. That can be done by modifying the file source/conf.py as follows (see also here):

extensions = [ 'sphinxjp.themes.revealjs', ]
html_theme = 'revealjs'
html_use_index = False

The setup is done. The presentation can be build by modifying the file source/index.rst. This is my example which you can find here:

=========================
My first try with reveals
=========================

.. revealjs:: A quick try with sphinxjp.themes.revealjs

    Let's how it goes

 .. rv_small::

    Created by `Xavier Dupré <http://www.xavierdupre.fr/blog/2014-02-01_nojs.html>`_ 

.. revealjs:: What's up

    Let's see how this text is displayed.
    And what about these bullet points:
        - bullet 1
        - bullet 2
        - bullet 3

    .. rv_note::

        hidden note

.. revealjs::

    .. revealjs:: The first slide comes horizontally.

        The first slide of a pile.

    .. revealjs:: The second slide comes vertically.

        Well, do you remember where you are.
        
    .. revealjs:: The third slide still comes vertically.

        I'm lost
        
.. revealjs::

    .. revealjs:: Conlusion

        I like it

    .. revealjs:: Plus

        It is easy to put online.

Or you can see that here:

XD blog

2014-02-01 Sphinx themes and presentation