module package

Module contents

A Sphinx example and cheat sheet.

Documenting Python Code

For documenting Python code, see module/__init__.py or the code example below:

class AClass:
    """
    Class docstring, with reference to the :mod:`module`, or another class
    :class:`module.AnotherClass` and its function :func:`module.AnotherClass.foo`.
    """

class AnotherClass:
    """
    Another class' docstring.
    """
    
    def foo(arg1, arg2):
        """
        A method's docstring with parameters and return value.
        
        Use all the cool Sphinx capabilities in this description, e.g. to give
        usage examples ...
        
        :Example:

        >>> another_class.foo('', AClass())        
        
        :param arg1: first argument
        :type arg1: string
        :param arg2: second argument
        :type arg2: :class:`module.AClass`
        :return: something
        :rtype: string
        :raises: TypeError
        """
        
        return '' + 1

Comments

.. comment This is a comment!

Basic Syntax

italic

bold

verbatim with special characters such as *, also useful for inline code examples

*italic*

**bold**

``verbatim with special characters such as *, also useful for inline code examples``

Headings

Level 2

Level 3
Level 4
Level 5

Note that level 5 does not impose any styling, but is added to the table of contents on the left.

Headings
########

Level 2
*******

Level 3
=======

Level 4
-------

Level 5
^^^^^^^

Lists

  • Item 1
  • Item 2
  • Item 3
  • Multi- line item
  1. Item 1
  2. Item 2
  3. Item 3
  4. Item 4
  5. Item 5
* Item 1
* Item 2
* Item 3

* Multi-
  line item

1. Item 1
2. Item 2
3. Item 3

#. Item 4
#. Item 5

Tables

Complex variant:

Header 1 Header 2
Cell 1.1 Cell 1.2
Multi-column
Cell 3.1 Multi-row
Cell 4.1

Another, simpler variant:

Header 1 Header 2
Cell 1.1 Cell 1.2
Cell 2.1 Cell 2.2 
+------------+------------+
| Header 1   | Header 2   |
+============+============+
| Cell 1.1   | Cell 1.2   |
+------------+------------+
| Multi-column            |
+------------+------------+
| Cell 3.1   | Multi-row  |
+------------+            |
| Cell 4.1   |            |
+------------+------------+

======== ========
Header 1 Header 2
======== ========
Cell 1.1 Cell 1.2
Cell 2.1 Cell 2.2
======== ========

Boxes

See also

See also box ...

Todo

To do box ...

Warning

Warning box ...

Code

Simple code box:

print('done ...')

Line numbers and language option:

1
print('done ...')

Math

Note that backslashes need to be escaped!

If the math isn’t rendered directly, refresh using Shift + F5 or Ctrl + Shift + R (in most browsers).

Inline: \(\alpha\)

Block:

\[\sum_{i = 1}^n w_i x_i\]
Inline: :math:`\alpha`

Block:

.. math::

    \sum_{i = 1}^n w_i x_i

Images and Figures

Image:

../images/pocoo.png

Figure:

Pocoo

Pocoo figure ...

Image:

.. image:: ../images/pocoo.png

Figure:

.. figure:: ../images/pocoo.png
    :align: center
    :alt: Pocoo
    :figclass: align-center
    
    Pocoo figure ...

Misc Elements

Topic:

My Topic

My topic text ...

Sidebar:

My Sidebar

My sidebar text ...

.. topic:: My Topic

    My topic text ...

.. sidebar:: My Sidebar
    
    My sidebar text ...

Citations

Citation in text [Stutz2015]

[Stutz2015]
  1. Stutz. Superpixel Segmentation: An Evaluation. GCPR, 2015.
 
Citation in text [Stutz2015]_

.. [Stutz2015] D. Stutz. Superpixel Segmentation: An Evaluation. GCPR, 2015.

Footnotes

The footnote section needs to be added at the end ...

Footnote [#f]_

.. comment:: ...

.. rubric:: Footnotes

.. [#f] Footenote text ...

Footnote [1]

Footnotes

[1]Footenote text ...
class module.AClass

Class docstring, with reference to the module, or another class module.AnotherClass and its function module.AnotherClass.foo().

class module.AnotherClass

Another class’ docstring.

foo(arg1, arg2)

A method’s docstring with parameters and return value.

Use all the cool Sphinx capabilities in this description, e.g. to give usage examples ...

Example: 
>>> another_class.foo('', AClass())
Parameters:
  • arg1 (string) – first argument
  • arg2 (module.AClass) – second argument
Returns:

something
Return type:

string
Raises:

TypeError