Sphinx as a Static Site Generator¶

Installing Sphinx¶

Installing sphinx is as easy as pip install sphinx (on Linux and Windows). pip will download a bunch of other dependencies (docutils, Jinja2, pygments as well). Once installed, check whether sphinx is available to you by typing $ sphinx-quickstart at the command line. This should give you a welcome message. We proceed from there in the next section. (On Windows, if you have added C:\Python27\Scripts to the Windows Path variable, the sphinx commands should be already available to be executed since the sphinx binaries are also installed in this location).

Creating the Sphinx directory structure¶

Go to your directory (say demo) where you want to create the content of your static site and execute the sphinx-quickstart command. It should display a welcome message and start a wizard asking you various questions about your new site.

• Root path: Select the default (current directory)
• Source and build directories: default
• Name prefix: Default
• Project name: Your project name (say, “Programming Notes”)
• Author name(s): The name of the author(s)
• Project version: 1.0 (say)
• Project release: 1 (say)
• Source file suffix: default (.rst)
• Name of your master document: index
• Epub builder: No
• autodoc, doctest, intersphinx extensions: No
• todo: Yes
• coverage: No
• pngmath: No
• mathjax: Yes
• ifconfig: No
• viewcode: No
• Makefile: Yes
• Windows command file: Yes

The executable now creates a directory structure, and you will see the directories _build, _static, _templates and the files conf.py, index.rst, make.bat, Makefile created in the current directory for you.

We will soon understand in detail what each of these are and how we can start creating content for the site. Before that, type make html in the directory where you created the directory structure. This command builds the HTML for your site, and places those files in the directory html under _build. You will notice that there is a index.html file in that directory. This is your homepage or the master page of your site. Open this file in your browser. You should see a web page similar to this one:

Adding content¶

Now, we shall see how we can add content to our static site. It is a two step process:

• Create a new file
• Add it to the index.rst file

For example, create a new file with the name page1.rst and add the following text to it:

Page 1
------

This is a new page

Sub-heading 1
=============

Sub-heading 2
=============

Now, add this page name to the to the file index.rst which should then look as follows:

Welcome to Programming Notes's documentation!
=============================================

Contents:

.. toctree::
    :maxdepth: 2

    page1



Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

Now, rebuild the HTML pages using make html. If you reopen (or refresh) the index.html page, you will see that it has links to the contents of page1.rst. The .. toctree directive does all the magic of creating the table of contents on this page, and you can control the depth of the table of contents using the number after :maxdepth.

print 'A line of Python'

Configuration¶

The default configuration generated by sphinx may well suffice your needs, but let us spend some time tinkering with it to customise the HTML output (and in the next section, use sphinx extensions).

conf.py in your static site root directory is a Python file which contains all the configuration details used by sphinx when you trigger a build process. There are a number of configuration statements for LaTex, Unix man page and Windows help file output, which you can remove, since we only plan to generate HTML output. That will leave the default and HTML specific configuration options. As you will notice, this file has been created from your responses to the sphinx-quickstart command. The conf.py file after tweaking and customizing looks like this (along with the associated comments; created using pycco).

There are a number of default themes that you can use and you can create your own too. See this page for details.

Read all about the options for HTML output here.

I also changed the index.rst file to have a different heading. Rebuild the HTML pages and now the index page looks similar to:

Builtin Extensions¶

Sphinx extensions extend Sphinx’s functionality in various ways. There are a number of builtin extensions, two of which we included during the initial setup: todo and mathjax.

.. todo::

   Add text here

# Include todos
todo_include_todos = True

.. math::

   ax^2 + bx + c = 0

   x_1 = \frac{-b+\sqrt{b^2-4ac}}{2a}
   x_2 = \frac{-b-\sqrt{b^2-4ac}}{2a}w

Custom Extensions¶

Besides the builtin extensions, there are a number of others written by various authors maintained in the sphinx-contrib repository.

You can clone the repository, and install each extension on its own, or you could use pip with the appropriate package name from PyPI.

.. youtube:: 8vwtgMkqE9o
        :width: 640
        :height: 480

.. venndiagram::

         data: 100, 80, 40, 20, 20, 20, 10

Publishing¶

To share your HTML pages on the Internet, you have various options.

git clone https://github.com/amitsaha/site.git
Cloning into 'site'...
warning: You appear to have cloned an empty repository.

git checkout -b gh-pages

touch .nojekyll

mkdir demo

git add .nojekyll
git add demo
git commit -m "Created .nojekyll and first commit of static HTML"

git push origin gh-pages

Conclusion¶

In this article, I have discussed how Sphinx can be used to create a set of HTML pages with the ability to embed code, images, YouTube videos and charts. We created the content in reStructuredText and then used Sphinx’s build tools to convert them into a set of standalone HTML pages. We also looked at a few ways we could host these pages and make them available publicly.

The demo Sphinx project can be found in demo.

In a next article, we will focus on creating documentation which is coupled with a software project and explore Sphinx’s various features useful in such a scenario.