reStructuredText and Sphinx =========================== Your content has parts with different uses in the text: titles, paragraphs, emphasized text, URL's with hyperlinks, index references. *Markup* is added to basic text content to identify these specific functions. It is better to identify logical function than the final appearance: The formatting for a mobile device is quite different than for a regular large html web page, which is different than the formatting for a page-oriented pdf file. In a WYSIWYG editor like MS-Word, the markup is largely hidden from you, and you mostly look at a version formatted for a page. If you are going to generate multiple final forms it is easier to see the functional markup directly. The trick is to keep the plain text concise and easily readable, so as to not obscure the underlying text your are editing. In the early days of the web there were no WYSIWYG editors, and html was edited in its raw form. Html markup is specifically designed for web pages and can get rather verbose. Later markup formats were structured text, and then its successor restructured text for single files, and then Sphinx extends restructured text to handle multiple file organization with indexing and cross-referencing. There are other markup systems, like *markdown*, but here we cover the system we used. In the html version of the output of this document, you should see the link for **source** in the left html frame. We use this document to show off some of the basic source markup. The only markup above in this page has been * the main section heading * paragraphs * italics and boldface * and now this bulleted list Look at the **source** to see the markup (link in the left frame of html output): * The chapter heading is set off with a separate line of equal signs. * Paragraphs are left justified and separated by a blank line. They are wrapped in the final formatting. * Italics is bracketed in *single asterisks*. Boldface is bracketed in **double asterisks**. * Bulleted lists look close to normal. See that the continuation lines like this one is indented to line up with the bullet text, not the bullet. All of this markup is very easy to recognize and enter in the plaintext version, though it looks better in the final formatted version. Using chapter headings for small parts of this presentation is overkill, and wastes space in the pdf version, but we get to see the format. This is a subsection -------------------- I chose dashes to indicate subsections. You need to use a consistent symbol, but there are many symbol characters that you can use to mark sub-sections. This is another subsection -------------------------- And inside subsections we can have sub-sub-sections, etc. This is a sub-sub-section ~~~~~~~~~~~~~~~~~~~~~~~~~ I chose tildas to identify sub-sub-sections. This is a set-off block of text. See the blank lines surrounding a block with *consistent* indentations, further than in the surrounding section. There may be several paragraphs in a set-off block. From the sub-sub-section back to a sub-section: Fancier Markup --------------- There are limits to this fairly obvious spatial markup. To mark a wider diversity of components, some explicit labels are needed. They come in two basic forms labeling - outside a paragraph, on a line starting with ".. " - inside the flow of a paragraph Indexing ~~~~~~~~~~ One of our favorite additions made by Sphinx is easy indexing. .. index:: index entry; simple On a set off line by itself:: .. index:: index entry; simple makes an index entry. Here the primary index entry is "index entry", and the secondary entry (after the semicolon) is "simple". .. index:: double: double entry; index entry Often we want to mark a place with two related idea, and want two index entries, reversing which is primary. You can do both simultaneously with the markup:: .. index:: double: double entry; index entry Look at the index and check. Footnotes ~~~~~~~~~~~ Here we have a footnote. [#doubleColon]_ Automatically numbered footnotes have a marking in place in the source paragraph text like :: [#doubleColon]_ and at the end of the section set off footnote text like :: .. [#doubleColon] If you look at the source, you see that we are using a double colon :: before the set off text to make it literal. The original footnote reference inside the paragraph is bracketed by ``[#`` and ``]_``. This follow the basic pattern in restructured text to use concise symbol combinations inside a paragraph that are unlikely to appear in normal text. Links ~~~~~~ There is also simple markup to do hyperlinks, both to web URL's and as cross references within a Sphinx document, like to :ref:`transformation`. More elaborate documents by some of the authors are http://introcs.cs.luc.edu and `Dr. Harrington's Python Tutorial `_. .. [#doubleColon] If you look at the source, you see that we are using a double colon :: before the set off text to make it literal. Multiple Files --------------- In many situations it is useful to break up a long document into separate files. This is particularly useful if you are collaborating. Separating and rearranging parts is very easy in Sphinx. Multi-file documents can easily be nested to any level with the toctree directive, like in the source for the `initial file for this document <_sources/index.txt>`_. File names listed under the toctree directive can also include a toctree directive. Just by moving single lines, you can rearrange sections. Numbering is reworked. Cross references still work.... This section just gave some of the flavor of Sphinx. Look at its web site, http://sphinx.pocoo.org/, for full documentation on installation, initiating a project, editing, and generating output formats.