RST Workshop: Overview

This documents provides a workshop audience with essential information about reStructuredText (RST).

The workshop goals are:

  1. Give the participants enough information to get them started using RST.

  2. To prompt the participants to think if RST is right for them.

Topics Covered

This workshop guides the learner through these topics:

  • Paragraphs and Inline Styles

  • Structural Elements

  • Paragraph Level Markup

  • Lists and Tables

  • Menu and Navigation

  • Linking, Images

  • Embedded HTML

  • Includes

  • Diagrams

  • Documenting Source Code (sphinx.ext.autodoc)

Some participants are IT professionals or developers who want to learn how Sphinx works. Therefore, the content of the workshop documentation will be on setting up Sphinx on a Linux server.

The result of this activity is found on page RST Workshop: Setting up a Sphinx Server.

Workshop Resource List

This list of curated sites will help you complete the tasks. Some sites explain some components better than other sites. Therefore, each task will put a link to the site that provides a clear explanation on how to complete it.

  1. This document! Click the View page source in the upper right hand corner to see the source code.

  2. https://rest-sphinx-memo.readthedocs.io/en/latest/ReST.html

  3. https://gist.github.com/ionelmc/e876b73e2001acd2140f

  4. https://docs.typo3.org/m/typo3/docs-how-to-document/master/en-us/WritingReST/CheatSheet.html

Workshop Tasks

Task

Create documentation using RST.

Topic

Getting Sphinx Running.

Overall Goal

You will create RST files that document how to set up Sphinx on a server and to serve the rendered content using Nginx.