Task 1: Page Structure

RST Headings

Heading tags provide the structural element of a page. Unlike traditional markdown, RST uses over and underlines.

RST has no official consensus on headings. This site states that

Normally, there are no heading levels assigned to certain characters as the structure is determined from the succession of headings. However, it is better to stick to the same convention throughout a project. For instance:

  • # with overline, for parts

  • * with overline, for chapters

  • = for sections

  • - for subsections

  • ^ for subsubsections

  • " for paragraphs

The RST Docutils site breaks down headings between document titles/subtitles and sections. TYPO3 Documentation states that “in reST, you can use different styles in any order you want”.

A common consensus is to use and over and underline for the document header, and then underlines for the other headers. The key is consistency in your documentation set.

Read the docs theme is popular among RST users. Therefore, this workshop will use the following headings used by sphinx_rtd_theme, which are:

******************
Document title
******************

Introduction text.


Header 1 (Document Section)
===========================

Header 1.1 (Document Subsection)
-----------------------------

Header 1.1.1 (Document Subsubsection)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Important

  1. The over or underlines can be longer than the header text, but not shorter.

  2. The over and underlines must be the same length


Task

Task 1: Create the page structure using appropriate heading tags

  1. Create a file with extension .rst.

  2. Give the document a title similar to, Setting up Sphinx

  3. Give the page some structure creating the first four headings using the appropriate heading tags

  4. Fix the build warning (WARNING: document isn't included in any toctree) by adding the page to the TOC in index.rst

    1. Add the name of the file (without the extension) under the toctree directive in index.rst.

      .. toctree::
        :maxdepth: 2
        :caption: Contents:
      
        getting-sphinx-running
      
  5. You can read more about the toctree directive in Task 7: Menus and Navigation


Text to add

Setting up Sphinx

  • Overview

  • Installing Sphinx

    • Spin up a VPS with your favorite Linux distro

    • Install Sphinx using the package manager

  • Configure Sphinx using sphinx-quickstart

  • Rendering to HTML

  • Adding Content

    • Default index.html

    • Create Folders

  • Install a Different Theme

    • Install Read the Docs Theme