Demo Docs

Page Status:Incomplete
Last Reviewed:2013-10-29

Contents:

Maaaaath!

This is a test. Here is an equation: \(X_{0:5} = (X_0, X_1, X_2, X_3, X_4)\). Here is another:

\[\nabla^2 f = \frac{1}{r^2} \frac{\partial}{\partial r} \left( r^2 \frac{\partial f}{\partial r} \right) + \frac{1}{r^2 \sin \theta} \frac{\partial f}{\partial \theta} \left( \sin \theta \, \frac{\partial f}{\partial \theta} \right) + \frac{1}{r^2 \sin^2\theta} \frac{\partial^2 f}{\partial \phi^2}\]

Giant tables

Header 1 Header 2 Header 3 Header 1 Header 2 Header 3 Header 1 Header 2 Header 3 Header 1 Header 2 Header 3
body row 1 column 2 column 3 body row 1 column 2 column 3 body row 1 column 2 column 3 body row 1 column 2 column 3
body row 1 column 2 column 3 body row 1 column 2 column 3 body row 1 column 2 column 3 body row 1 column 2 column 3
body row 1 column 2 column 3 body row 1 column 2 column 3 body row 1 column 2 column 3 body row 1 column 2 column 3
body row 1 column 2 column 3 body row 1 column 2 column 3 body row 1 column 2 column 3 body row 1 column 2 column 3

API Test

Test Module for sphinx_rtd_theme.

class test_py_module.test.Foo(qux, spam=False)[source]

Docstring for class Foo.

This text tests for the formatting of docstrings generated from output sphinx.ext.autodoc. Which contain reST, but sphinx nests it in the <dl>, and <dt> tags. Also, <tt> is used for class, method names and etc, but those will always have the .descname or .descclassname class.

Normal <tt> (like the <tt> I just wrote here) needs to be shown with the same style as anything else with ``this type of markup``.

It’s common for programmers to give a code example inside of their docstring:

from test_py_module import Foo

myclass = Foo()
myclass.dothismethod('with this argument')
myclass.flush()

print(myclass)
__init__(qux, spam=False)[source]

Start the Foo.

Parameters:
  • qux (string) – The first argument to initialize class.
  • spam (bool) – Spam me yes or no...
add(val1, val2)[source]

Return the added values.

Parameters:
  • val1 (int) – First number to add.
  • val2 (int) – Second number to add.
Return type:

int
another_function(a, b, **kwargs)[source]

Here is another function.

Parameters:
  • a (int) – The number of green hats you own.
  • b (int) – The number of non-green hats you own.
  • kwargs (float) – Additional keyword arguments. Each keyword parameter should specify the name of your favorite cuisine. The values should be floats, specifying the mean price of your favorite dish in that cooking style.
Returns:

A 2-tuple. The first element is the mean price of all dishes across cuisines. The second element is the total number of hats you own: \(a + b\).
Return type:

tuple
Raises ValueError:
 

When a is not an integer.
bar = 1

Doc comment for class attribute Foo.bar. It can have multiple lines.

baz = 2

Docstring for class attribute Foo.baz.

capitalize(myvalue)[source]

Return a string as uppercase.

Parameters:myvalue (string) – String to change
Return type:string
flox = 1.5

Doc comment for Foo.flox. One line only.

qux = None

Doc comment for instance attribute qux.

spam = None

Docstring for instance attribute spam.

Optional 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'])

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

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

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

Code test

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

{
"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"
}

Code with Sidebar

A code example

With a sidebar on the right.

 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
40
# -*- coding: utf-8 -*-
"""Test Module for sphinx_rtd_theme."""


class Foo:

    r"""Docstring for class Foo.

    This text tests for the formatting of docstrings generated from output
    ``sphinx.ext.autodoc``. Which contain reST, but sphinx nests it in the
    ``<dl>``, and ``<dt>`` tags. Also, ``<tt>`` is used for class, method names
    and etc, but those will *always* have the ``.descname`` or
    ``.descclassname`` class.

    Normal ``<tt>`` (like the <tt> I just wrote here) needs to be shown with
    the same style as anything else with ````this type of markup````.

    It's common for programmers to give a code example inside of their
    docstring::

        from test_py_module import Foo

        myclass = Foo()
        myclass.dothismethod('with this argument')
        myclass.flush()

        print(myclass)

    """

    #: Doc comment for class attribute Foo.bar.
    #: It can have multiple lines.
    bar = 1

    flox = 1.5   #: Doc comment for Foo.flox. One line only.

    baz = 2
    """Docstring for class attribute Foo.baz."""

    def __init__(self, qux, spam=False):

Boxes

Tip

Equations within a note \(G_{\mu\nu} = 8 \pi G (T_{\mu\nu} + \rho_\Lambda g_{\mu\nu})\).

Note

Equations within a note \(G_{\mu\nu} = 8 \pi G (T_{\mu\nu} + \rho_\Lambda g_{\mu\nu})\).

Danger

Equations within a note \(G_{\mu\nu} = 8 \pi G (T_{\mu\nu} + \rho_\Lambda g_{\mu\nu})\).

Warning

Equations within a note \(G_{\mu\nu} = 8 \pi G (T_{\mu\nu} + \rho_\Lambda g_{\mu\nu})\).

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 my code documentation for it.

Note

Every other line in this table will have white text on a white background.
This is bad.
Example
Thing1
Thing2
Thing3

Emphasized lines with line numbers

1
2
3
4
5
def some_function():
    interesting = False
    print 'This line is highlighted.'
    print 'This one is not...'
    print '...but this one is.'

Citation

Here I am making a citation [1]

[1]This is the citation I made, let’s make this extremely long so that we can tell that it doesn’t follow the normal responsive table stuff.