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
Look at the source to see the markup (link in the left frame of html output):
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.
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.
And inside subsections we can have sub-sub-sections, etc.
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:
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
One of our favorite additions made by Sphinx is easy indexing.
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”.
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.
Here we have a footnote. [1]
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.
There is also simple markup to do hyperlinks, both to web URL’s and as cross references within a Sphinx document, like to Transformation.
More elaborate documents by some of the authors are http://introcs.cs.luc.edu and Dr. Harrington’s Python Tutorial.
| [1] | If you look at the source, you see that we are using a double colon :: before the set off text to make it literal. |
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.
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.