make_project.rst

Making Project

Run sphinx-quickstart

To create a sphinx project, type blow.

$ sphinx-quickstart

Sphinx-quickstart commands asks some of questions. You must enter at least three items. Other questions are just type "Enter" key.

1. Project Name
2. Version
3. Author Name

This is my own bookreview page, let's set "Book Review" as project name, today as version and my name as author.

.. toctree::

   sphinxquickstart

Let's make page structure

Now you have created an document skeleton. Let's add some pages and create whole document.

Note

This assumes default directory setting (not separete source and build directory and prefix is _).

I want to introduce "Expert Python Programming" and "The Art of Community", one revies by one file. The page structure is below:

index.rst
  +- expert_python.rst
  +- art_of_community.rst

When you make a document by Sphinx, you write some directives in the document. The most important directive is .. toctree:: . This directive defines the document tree structure. index.rst which is master document already has this toctree directive, let's add some items. We omit some header lines of index.rst file because these are just a comment.

index.rst:

Welcome to Book Review's documentation!
=======================================

Contents:

.. toctree::
   :maxdepth: 2

   expert_python
   art_of_community

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

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

Note

You should insert "Empty Line" between :maxdepth: and file names. And you should not write a file extention such as ".rst".

Next, write child files.

Note

Charactor encodings should be UTF-8.

expert_python.rst:

=========================
Expert Python Programming
=========================

:Author: Tarek
:Publisher: Packt Publishing

Description
================

Expert Python Programming is for the python experts. It describes
how to use non-major python functions, using test tools to build
application, continous integration and so on with a lot of
citations about algorithms inside python.

art_of_community.rst:

====================
The Art of Community
====================

:Author: Jono Bacon (Ubuntu Linux community manager)
:Publisher: O'reilly

Description
================

This describes community management. How to create community, tools
for community management, how to measure community, management
organization. What's more, how to make Buzz, physical event, or how
to find sponsers. All topics are backed by a great deal of experience.

Once you finish editing the file, execute this command to create HTML files.

$ make html

The HTML files are created in the _build/html. Congratulation! This is the document which is created by Sphinx.

You can see the titles of child pages are put on the toctree directive. This toctree mechanism is a most important thing of the Sphinx.

Inside of toctree

All of Sphinx pages include a section title.

The three examples listed above use = as a section title. In the Sphinx, you can use #, *, =, -, ^, ~, ". There are two way to write section title. One is write underlining and overlining, other is only overlining. These two way make different section level.

And also different charactor creates different section level. Section level is defined the order in the file. At the examples listed above, a title (underlining and overlining =) is level 1, contents (only underlining =) is level 2.

For the Python documentation, this convention is used which you may follow:

- ``#`` with overline, for parts
- ``*`` with overline, for chapters
- ``=``, for sections
- ``-``, for subsections
- ``^``, for subsubsections
- ``"``, for paragraphs

toctree directive retrieves child section title and make table of contents. In this time maxdepth option is 2, toctree make title until level 2. This enables the document easy to find desired information even the document has deep structure.

You can set multiple toctrees in one page. And section title level where toctree is placed also affects. If section title where toctree is placed is level 2, level 1 of child document and level 2 of section title is used for level 3 and level 4 of parent document.

Below image shows this. If you set toctree as maxdepth 2, toctree includes level 1 title of grandchild and also red colored titles.

Note

If a file has no section title, warning will be displayed.

Next, go to :doc:`make your Sphinx document more powerful <use_markup>` which introduces some markups and directives.