Sitemap¶

1.5.1   Images¶

This is a caption for a figure.

A figure is an image with a caption and/or a legend:

Cats on the internet are fine. But dogs on the internet are fanTAStic!

1.3.1   Section Title¶

That’s a section title: the text just above this line.

1.3.2   Paragraphs¶

A paragraph.

1.3.3   Bullet Lists¶

• A bullet list

  • Nested bullet list.
  • Nested item 2.

• Item 2.

  Paragraph 2 of item 2.

  • Nested bullet list.
  • Nested item 2.
    • Third level.
    • Item 2.
  • Nested item 3.

1.3.4   Enumerated Lists¶

1. Arabic numerals.

   1. lower alpha)
      1. (lower roman)
         1. upper alpha.
            1. upper roman)

2. Lists that don’t start at 1:

   3. Three
   4. Four
   3. C
   4. D
   3. iii
   4. iv

3. List items may also be auto-enumerated.

1.3.5   Definition Lists¶

Term

Definition

Term : classifier

Definition paragraph 1.

Definition paragraph 2.

Term

Definition

1.4.1   Field Lists¶

Here’s an example of a field list:

1.4.2   Option Lists¶

For listing command-line options:

There must be at least two spaces between the option and the description.

1.5.1   Line Blocks¶

Take it away, Eric the Orchestra Leader!

A one, two, a one two three four

Half a bee, philosophically,

must, ipso facto, half not be.

But half the bee has got to be,

vis a vis its entity. D’you see?

But can a bee be said to be

or not to be an entire bee,

when half the bee is not a bee,

due to some ancient injury?

Singing...

1.5.2   Block Quotes¶

Block quotes consist of indented body elements:

My theory by A. Elk. Brackets Miss, brackets. This theory goes as follows and begins now. All brontosauruses are thin at one end, much much thicker in the middle and then thin again at the far end. That is my theory, it is mine, and belongs to me and I own it, and what it is too.

—Anne Elk (Miss)

1.5.3   Doctest Blocks¶

>>> print 'Python-specific usage examples; begun with ">>>"'
Python-specific usage examples; begun with ">>>"
>>> print '(cut and pasted from interactive Python sessions)'
(cut and pasted from interactive Python sessions)

1.9.1   External targets¶

Explicit external targets are interpolated into references such as “Python”.

Here’s a reference to the Definitinve RST Reference documentation.

You can refer to another rst document within the site with a Sphinx directive. A reference to the 1   Examples of Code in rst like this: :ref:`rst_code`

Targets may be indirect and anonymous. Thus this phrase may also refer to the Targets section.

1.9.2   Target Footnotes¶

If you use the .. target-notes:: directive, footnotes for all external references will be generated, and the footnotes themselves will be put after that directive. (Thus you usually want to put the directive at the bottom of a document so the footnotes will be at the bottom – the foot of the document.

Target footnoes are not used in this document. But you can see it in action in this one <rst_tiny>.

1.1.1   Inline code and references¶

reStructuredText is a markup language. It can use roles and declarations to turn reST into HTML.

In reST, *hello world* becomes <em>hello world</em>. This is because a library called Docutils was able to parse the reST and use a Writer to output it that way.

If I type ``an inline literal`` it will wrap it in <tt>. You can see more details on the Inline Markup on the Docutils homepage.

Also with sphinx.ext.autodoc, which I use in the demo, I can link to test_py_module.test.Foo. It will link you right to my code documentation for it.

1.2.1   class directive and parameter args¶

At this point optional parameters cannot be generated from code. However, some projects will manually do it, like so:

This example comes from django-payments module docs.

class payments.dotpay.DotpayProvider(seller_id, pin[, channel=0[, lock=False], lang='pl'])¶

param seller_id:
	Seller ID assigned by Dotpay
param pin:	PIN assigned by Dotpay
param channel:	Default payment channel (consult reference guide)
param lang:	UI language
param lock:	Whether to disable channels other than the default selected above

This backend implements payments using a popular Polish gateway, Dotpay.pl.

Due to API limitations there is no support for transferring purchased items.

This example uses the .. class:: directive to format payments.dotpay.DotpayProvider(seller_id, pin[, channel=0[, lock=False], lang='pl']) and automatically put the word class in front of it. The :param args follow the class line. The optional :param args nicely format the parameters.

Here’s the rst for the entire example above, including the references:

At this point optional parameters cannot be generated from code.
However, some projects will manually do it, like so:

This example comes from django-payments module docs.

.. class:: payments.dotpay.DotpayProvider(seller_id, pin[, channel=0[, lock=False], lang='pl'])

    :param seller_id: Seller ID assigned by Dotpay
    :param pin: PIN assigned by Dotpay
    :param channel: Default payment channel (consult reference guide)
    :param lang: UI language
    :param lock: Whether to disable channels other than the default selected above

   This backend implements payments using a popular Polish gateway, Dotpay.pl.

   Due to API limitations there is no support for transferring purchased items.

.. _cannot be generated from code: https://groups.google.com/forum/#!topic/sphinx-users/_qfsVT5Vxpw
.. _django-payments module docs: http://django-payments.readthedocs.org/en/latest/modules.html#payments.authorizenet.AuthorizeNetProvider

1.2.2   parsed-literal¶

Using the ..parsed-literal:: directive will show text without reformatting it. It will do some simple formatting (coloring) but will often show the text in an ugly, large monospaced font. (Although you can change this with your own rst template.)

# parsed-literal test
curl -O http://someurl/release-0.23-SNAPSHOT.tar-gz

Here’s the rst for the above:

.. parsed-literal::

    # parsed-literal test
    curl -O http://someurl/release-0.23-SNAPSHOT.tar-gz

1.2.3   code-block¶

The .. code-block:: directive looks much better than .. parsed-literal::. (At least with the default Read The Docs template.) The .. code-block:: directive will try to display the text that follows it as programming code. If you specify a language that rst knows about, it will also format the text in a way that makes sense for that language.

Here’s and example of a code block without any formatting or coloring:

print "Hello world"

def some_function():
    interesting = False
    if interesting print 'This is a nonsensical function.'

The language specified is text. That tells rst to not apply any formatting or coloring.

text
.. code-block:: text

    print "Hello world"

    def some_function():
        interesting = False
        if interesting print 'This is a nonsensical function.'

You must specify a language after .. code-block::. If you don’t rst will produce a console warning and won’t display the code at all.

Here’s that same example with ruby specified as the language. With the language specified, keywords are now nicely colored:

print "Hello world"
def some_function():
    interesting = False
    if interesting print 'This is a nonsensical function.'

Here’s the rst; the only difference is the word ruby after the .. code-block:: directive to specify the language. (Note the space required between .. code-block:: and ruby!)

.. code-block:: ruby

    print "Hello world"

    def some_function():
        interesting = False
        if interesting print 'This is a nonsensical function.'

{
"windows": [
    {
    "panes": [
        {
        "shell_command": [
            "echo 'did you know'",
            "echo 'you can inline'"
        ]
        },
        {
        "shell_command": "echo 'single commands'"
        },
        "echo 'for panes'"
    ],
    "window_name": "long form"
    }
],
"session_name": "shorthands"
}

1.2.4   Include code from a source file¶

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39

import java.util.concurrent._
import scala.util.DynamicVariable

package object common {

  val forkJoinPool = new ForkJoinPool

  abstract class TaskScheduler {
    def schedule[T](body: => T): ForkJoinTask[T]
    def parallel[A, B](taskA: => A, taskB: => B): (A, B) = {
      val right = task {
        taskB
      }
      val left = taskA
      (left, right.join())
    }
  }

  class DefaultTaskScheduler extends TaskScheduler {
    def schedule[T](body: => T): ForkJoinTask[T] = {
      val t = new RecursiveTask[T] {
        def compute = body
      }
      Thread.currentThread match {
        case wt: ForkJoinWorkerThread =>
          t.fork()
        case _ =>
          forkJoinPool.execute(t)
      }
      t
    }
  }

  val scheduler =
    new DynamicVariable[TaskScheduler](new DefaultTaskScheduler)

  def task[T](body: => T): ForkJoinTask[T] = {
    scheduler.value.schedule(body)
  }

This is taken from the actual source file. The rst code can reference either absolute file paths or relative file paths. (Absolute file paths are brittle, so should be avoided of course.) With relative file paths, rst can only refer to files under the project’s .../src/sphinx directory. But you can create a symbolic link in .../src/sphinx that refers to some other file. That’s how this code is referenced: within rst, it refers to a file in .../src/sphinx that is actually a symbolic link to the real source file.

1.2.5   literalinclude includes content from a file without interpreting it¶

If you want to include the contents of a file but not have rst interpret it, use the literalinclude directive. For example, if you want to show the contents of a file (or parts of it) but that file contains text that are rst directives or some other code that rst might read as instructions and you don’t want rst to execute (do) those directives, use literalinclude.

(TBD: link to the rst documentation)

Here’s how literalinclude was used to read lines from a source file and include them above:

.. literalinclude:: /package.scala
     :language: scala
     :linenos:
     :lines: 1-40
      :caption: Live code from /src/main/scala/common/package.scala

1.2.6   parsed-literal shows text without interpreting it¶

And here is how to get the above to show as code and not be interpreted by the rst parser as directives:

.. parsed-literal::
    .. literalinclude:: /package.scala
        :language: scala
        :linenos:
        :lines: 1-40
        :caption: Live code from /src/main/scala/common/package.scala