First Changes

Sphinx uses the reStructuredText document format, which provides a simple yet powerful text file markup syntax. ReStructuredText can be converted to many different output formats (notably HTML and PDF) while maintaining a legible source. The reStructuredText syntax is similar to wiki markup languages.

Editing the Index

Open index.txt in your text editor. The default document contains

• an explanatory comment

• two sections

• the master table of contents tree (“toctree”) that houses your site structure

  The default tree is empty.

Exercises

1. Look over the reStructuredText syntax

2. Look at the source of this page by clicking the source link.

3. In your site’s index.txt, delete the second section—Indices and tables–along with its content.

   Run make html and reload the home page to see your changes.

4. Add a couple of paragraphs of text. Be sure to include examples of emphasized, strong, and monospaced text.

5. Add three lists, one of which is a nested list.

   1. One list should be an explicitly numbered list

   2. One list should be a bullet list

   3. One list should be auto numbered

      Challenge

      Make your auto numbered list start with something other than 1.

6. Add a hyperlink

7. Separate your document into sections (and possibly subsections) by adding appropriate headings.

8. Add an image to your document

Adding a Second Document

While Sphinx and reStructuredText are useful for creating standalone documents, the real power of Sphinx stems from its ability to create web sites. Sphinx automates the process of handling navigation and styling through the use of templates and themes. When using Sphinx to create your site, you can focus on the content of the site, creating it from reStructuredText documents which Sphinx weaves together to create the final result.

To create a second document for your site:

1. Create a text file called about.txt. Populate your new document with some content.

2. In your site’s index.txt, add a reference to your about document in the toctree:

   .. toctree::
       :maxdepth: 2
   
       about
   

3. Run make html and reload the home page to see your changes.

4. Since the navigation links appear in the sidebar on the left, you may wish to remove them from the document content, like this:

   .. toctree::
       :hidden:
   
       about
   

Adding a Logo

Sphinx allows you to add a logo to your site:

1. Create or find a logo image and save it to your project’s _static folder.

2. Edit the file conf.py in your text editor, changing the configuration option html_logo to the name of your logo file:

   html_logo = 'logo.png'