Emencia's Sphinx documentations

Sommaire

Install
Usage

This is the repository to contains all Sphinx documentations projects created for Emencia.

The repository is a unique buildout project so you install it and can build one or all documentations.

Actually the buildout install Sphinx and some additional themes (like sphinx_bootstrap_theme or sphinx_rtd_theme) so a documentation can use them instead of the Sphinx's Builtin themes. But if you want you can use another theme, just remember to add its dependancies in the versions.cfg if your it need some ones.

All documentation projects sources live in the projects/ directory;
All builded documentation should have a symbolic link in builds/ directory that can be easily mounted on a webserver to publish the docs;

Install

To install the buildout project just do the common :

make install

Actually, you will have to build all the project you want to publish and so enter in each project directory and build them, for example if you want to publish the toto project :

cd projects/toto
make html

Usage

Remember to activate the virtual environnment before everything else (everytime you use it, not only after the first install) :

source bin/activate

Then you can enter in your documentation directory and use its Makefile to build the doc like this :

cd projects/mydoc
make html

If you need to use a Python interpreter that is aware of installed eggs, use eggedpy.

All common command-line scripts from Sphinx are available within the bin/ directory (like sphinx-quickstart, sphinx-builder, etc..) and aware of the installed eggs.

Also, in fact this is not required that your documentation project is a Sphinx project, it can be a simple unique RST document. Like for Sphinx, the common command-line scripts from docutils (like rst2html.py and others) are installed in the bin/ directory and aware of the installed eggs. But you will have to add Makefile with the html action to easily build your document in a _build/html directory like with a Sphinx project.

Documentations index

In the builds/ directory there is a index.html generated from the command (only available from the base dir of the repository) :

make index

It will scan through the builds/ to find all directories that contains an index.html file and add their link to the HTML list.

Add a new Sphinx documentation project

Use the interactive Sphinx quickstart command :

sphinx-quickstart

Answer to the question, note that if you execute this command from the root of the repository, the first question ask you if you want to create the project on the root (eg: .), this is wrong NEVER LET THIS HAPPEN, else specify a directory name (dont need to exists) for your project. Or if you prefer, create the directory before, enter to it, execute the quickstart command then you can let the default value for the first question.

When it's done, just go to the builds/ repository directory and make a symbolic link to the new documentation's HTML build directory (even if it doesn't exists yet) then re-generate the main builds index file to display the link to the new documentation.

Example

We will create a new project called dummy using the quickstart command :

cd projects/
sphinx-quickstart

Watch below for answers to the interactive prompt :

Welcome to the Sphinx 1.2.3 quickstart utility.

Please enter values for the following settings (just press Enter to
accept a default value, if one is given in brackets).

Enter the root path for documentation.
> Root path for the documentation [.]: dummy

You have two options for placing the build directory for Sphinx output.
Either, you use a directory "_build" within the root path, or you separate
"source" and "build" directories within the root path.
> Separate source and build directories (y/n) [n]:

Inside the root directory, two more directories will be created; "_templates"
for custom HTML templates and "_static" for custom stylesheets and other static
files. You can enter another prefix (such as ".") to replace the underscore.
> Name prefix for templates and static dir [_]:

The project name will occur in several places in the built documentation.
> Project name: Dummy doc
> Author name(s): Sarah Connor

Sphinx has the notion of a "version" and a "release" for the
software. Each version can have multiple releases. For example, for
Python the version is something like 2.5 or 3.0, while the release is
something like 2.5.1 or 3.0a1.  If you don't need this dual structure,
just set both to the same value.
> Project version: 1.0
> Project release [1.0]:

The file name suffix for source files. Commonly, this is either ".txt"
or ".rst".  Only files with this suffix are considered documents.
> Source file suffix [.rst]:

One document is special in that it is considered the top node of the
"contents tree", that is, it is the root of the hierarchical structure
of the documents. Normally, this is "index", but if your "index"
document is a custom template, you can also set this to another filename.
> Name of your master document (without suffix) [index]:

Sphinx can also add configuration for epub output:
> Do you want to use the epub builder (y/n) [n]:

Please indicate if you want to use one of the following Sphinx extensions:
> autodoc: automatically insert docstrings from modules (y/n) [n]:
> doctest: automatically test code snippets in doctest blocks (y/n) [n]:
> intersphinx: link between Sphinx documentation of different projects (y/n) [n]:
> todo: write "todo" entries that can be shown or hidden on build (y/n) [n]:
> coverage: checks for documentation coverage (y/n) [n]:
> pngmath: include math, rendered as PNG images (y/n) [n]:
> mathjax: include math, rendered in the browser by MathJax (y/n) [n]:
> ifconfig: conditional inclusion of content based on config values (y/n) [n]:
> viewcode: include links to the source code of documented Python objects (y/n) [n]:

A Makefile and a Windows command file can be generated for you so that you
only have to run e.g. `make html' instead of invoking sphinx-build
directly.
> Create Makefile? (y/n) [y]:
> Create Windows command file? (y/n) [y]: n

Creating file dummy/conf.py.
Creating file dummy/index.rst.
Creating file dummy/Makefile.

Finished: An initial directory structure has been created.

You should now populate your master file dummy/index.rst and create other documentation
source files. Use the Makefile to build the docs, like so:
make builder
where "builder" is one of the supported builders, e.g. html, latex or linkcheck.

Ok it is created, now make the symbolic link :

cd builds
ln -s ../dummy/_build/html dummy

Then add a .gitignore file to never commit the builded HTML :

cd dummy
echo '_build' > .gitignore

Now build the HTML doc :

make html

Finally generate again the HTML index file to add the link to your new documentation :

cd ../
make index

And voila! Remember to commit your new project to the repository.

Use the bootstrap theme within your documentation

You will need to edit the project's conf.py file, search for the line html_theme = 'default (probably around the line 101 on a fresh project) and replace it with the following code :

html_theme = 'default'
try:
    import sphinx_bootstrap_theme
except ImportError:
    pass
else:
    html_theme = 'bootstrap'
    html_theme_path = sphinx_bootstrap_theme.get_html_theme_path()

    # Theme options are theme-specific and customize the look and feel of a theme
    # further.  For a list of options available for each theme, see the
    # documentation.
    html_theme_options = {
        'bootswatch_theme': "yeti",
    }

Note the conditional import, this is to ensure compatibility if you move your documentation out of this repository, so you can build it without to install sphinx_bootstrap_theme.

See the sphinx_bootstrap_theme documentation to know all settings you can override.

Now you can rebuild your documentation, it will use the right theme.

Use the RTD theme within your documentation

You will need to edit the project's conf.py file, search for the line html_theme = 'default (probably around the line 101 on a fresh project) and replace it with the following code :

html_theme = 'default'
try:
    import sphinx_rtd_theme
except ImportError:
    pass
else:
    html_theme = "sphinx_rtd_theme"

    html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]

Note the conditional import, this is to ensure compatibility if you move your documentation out of this repository, so you can build it without to install sphinx_rtd_theme.

See the sphinx_rtd_theme documentation to know all settings you can override.

Now you can rebuild your documentation, it will use the right theme.

Add a simple RST document

Like for Sphinx, the common command-line scripts from docutils (like rst2html.py and others) are installed in the bin/ directory and aware of the installed eggs.

This is free to your needs, but you will have to add a Makefile with the html action to easily build your document in a _build/html directory like with a Sphinx project.

The easy way is to copy projects/readme to a new name and use it to start your document.

Like for a Sphinx documentation project, you will have to add its symbolic link in the builds/ directory :

cd builds
ln -s ../dummy/_build/html dummy

Remember to commit your new project to the repository.