Step 4: Creating Content in Sphinx

Objective: Create a simple page in Sphinx using RST.

Note

Unfortunately, MobaExterm text editor does not work with Cyrillic. It only accepts ASCII. Here are some options for modifying the content file.

  • Use nano in the terminal.

  • Create the files using your favorite text editor, then drop and drag them to the file browser in MobaExterm (easiest).

    • Be sure to navigate to the project folder before uploading them.

  • Upload them using an FTP client.

../../_images/mobaexterm-drop-and-drag.png

Drop files in MobaExterm to upload

Sphinx

Here are a few things to note when working with Sphinx

  1. Our Sphinx build includes the sphinx_autobuild extension, which detects when a file has changed and then automatically processes the changes.

  2. The HTML files from the build process reside in folder _build.

    • Do not modify files in this folder. These files are built dynamically.

    • Sometimes, deleted files reside in the folder. Remove the folder to trigger a rebuild using rm -r _build

  3. Sphinx converts .rst files to .html files.

  4. The default page is index.rst, which is what you see when you view the page in the browser.

  5. Sphinx is very particular about syntax. One space will alter the output.

  6. Use the resources in Sphinx and Read the Docs Resources.

Hint

Use the Online Sphinx editor to help you get started with RST.

4.4.1 Adding Content

These instructions will get you started.

  1. Create a new .rst file. (We’ll use example.rst for these instructions.)

  2. Add a heading to the file. See Sphinx’s reStructuredText primer for other heading levels.

    ***************
    This is an H1
    ***************
    
    Here is some text for file example.rst.
    
    This is an H2 heading
    ======================
    
    Here is content under heading two.
    
  3. Add additional content using the samples from the Sphinx and Read the Docs guides.

  4. Edit the index.rst file.

    • Add example in the .. toctree:: section

      .. toctree::
          :maxdepth: 2
          :caption: Contents:
      
          example
      
      This text will show after the table of contents.
      
    • Sphinx will look for example.rst and then add the file to the table of contents.

4.4.2 Rebuilding Sphinx

Sometimes you need to rebuild the HTML files to clear old documents or perform a manual build to view the errors and warnings.

Soft rebuild

  1. You can trigger a build event by executing make html.

  2. Run this command to build the directory and display errors and warnings.

    Using docker run
    # docker exec <container_name> <command>
    docker exec sphinx-server make html
    
    Using docker-compose
    # docker-compose exec <service_name> <command>
    docker-compose exec sphinx make html
    
    • Notice the warning message: checking consistency... /web/example.rst: WARNING: document isn't included in any toctree

    Output
    root@vps298933:~/sphinx-server# docker-compose exec sphinx make html
    Running Sphinx v1.8.5
    loading translations [ru]... done
    building [mo]: targets for 0 po files that are out of date
    building [html]: targets for 2 source files that are out of date
    updating environment: 2 added, 0 changed, 0 removed
    reading sources... [100%] index
    looking for now-outdated files... none found
    pickling environment... done
    checking consistency... /web/example.rst: WARNING: document is not included in any toctree
    done
    preparing documents... done
    writing output... [100%] index
    generating indices... genindex
    writing additional pages... search
    copying static files... done
    copying extra files... done
    dumping search index in Russian (code: ru) ... done
    dumping object inventory... done
    build succeeded, 1 warning.
    
    The HTML pages are in _build/html.
    root@vps298933:~/sphinx-server#