2016/10/29 - Sphinx

Feature

  • Sphinx is a tool that makes it easy to create intelligent and beautiful documentation.

  • Based on reStructuredText.

  • Output formats: HTML (including Windows HTML Help), LaTeX (for printable PDF versions), ePub, Texinfo, manual pages, plain text.

Installation

Install on Linux. Click me to see the tutorial.

Getting Start

  • Using command:

    $ sphinx-quickstart

to set up a source directory and creates a default conf.py with the most useful configuration values from a few questions it asks you. Just run.

  • toctree

.. toctree::
 :maxdepth: 2
 :glob:

 ./tmp/glob
Note

maxdepth means it will show at most 2 layers, glob can make your link to another .rst file ( in this example, the file is ./tmp/glob.rst ). More details and examples click here.

Running the build

sphinx-quickstart script creates a Makefile and a make.bat which make life even easier for you: with them you only need to run

make html

to build HTML docs in the build directory you chose. Execute make without an argument to see which targets are available.

reStructuredText syntax

Click me to see Quick reStructuredText page.

  • Blank lines and space should always keep in mind.

  • Image syntax:

    .. image:: images/image.jpg

  • Substitution:

    Insert |image1| here.

.. |image1| image:: images/image1.jpg