About Sphinx¶
Sphinx is a tool for making documentation. It was originally created for the Python documentation, but is now used for many other software projects.
Sphinx uses reStructuredText as its markup language. It can produce HTML, LaTeX, ePub and PDF documents.
Source: https://www.sphinx-doc.org
Getting started¶
After installation, you can get started quickly with the tool sphinx-quickstart. Just enter:
sphinx-quickstart
Answer each customization question with yes or no. Be sure to say yes to the autodoc extension. The sphinx-quickstart creates a directory with several documents:
conf.py
file, the default configuration fileindex.rst
file, the master document
The conf.py
file let’s you configure all aspects of Sphinx.
The index.rst
is the entry page for your documentation.
It contains the toctree
directive which determines the files to include.
For this project it looks like this:
.. toctree::
:maxdepth: 2
:caption: Contents:
1_intro/intro
2_draw/draw
3_image/image
...
To build the HTML pages just run:
make html
To make the PDF document run:
make pdf
reStructuredText¶
reStructuredText (.rst) is the default markup language used with Sphinx. It is important to know that:
- paragraphs are separated by one or more blank lines
- indentation is significant
Inline styles¶
Inside text you can use:
- one asterisk for italics
- two asterisks for bold
- backquotes for
code
Lists¶
This code:
1 2 3 4 5 6 | * This is a bulleted list.
* It has two items, the second
item uses two lines.
#. This is a numbered list.
#. It has two items too.
|
produces this result:
- This is a bulleted list.
- It has two items, the second item uses two lines.
- This is a numbered list.
- It has two items too.
Admonitions¶
Danger
Be careful with this code!
Tip
Be careful with this code!
Warning
Be careful with this code!
Footnotes¶
This is a footnote [1] inside a text, this is another one [2].
Footnotes
[1] | Text of the first footnote |
[2] | Text of the second footnote |
Horizontal list¶
To add a horizontal list add this code:
.. hlist::
:columns: 3
* happy
...
|
|
|
Include from a file¶
It is possible to include a Python object (class, method) from a file. For example you can include a class definition with:
.. literalinclude:: 5_app/app.py
:pyobject: Rectangle
:linenos:
:emphasize-lines: 5-7
resulting in
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 | class Rectangle(Node):
"""Draw a rectangle on the screen."""
options = { 'fg': Color('green'),
'bg': Color('black'),
'thickness': 2}
def __init__(self, **options):
super().__init__(**options)
self.set_options(Rectangle, options)
self.render()
def render(self):
self.img0 = pygame.Surface(self.rect.size, flags=SRCALPHA)
if self.fg != None:
pygame.draw.rect(self.img0, self.fg, Rect(0, 0, *self.rect.size), 0)
pygame.draw.rect(self.img0, self.bg, Rect(0, 0, *self.rect.size), self.thickness)
self.img = self.img0.copy()
|
Or you can include just a method definition with:
.. literalinclude:: 5_app/app.py
:pyobject: Rectangle.render
resulting in
def render(self):
self.img0 = pygame.Surface(self.rect.size, flags=SRCALPHA)
if self.fg != None:
pygame.draw.rect(self.img0, self.fg, Rect(0, 0, *self.rect.size), 0)
pygame.draw.rect(self.img0, self.bg, Rect(0, 0, *self.rect.size), self.thickness)
self.img = self.img0.copy()
Directives¶
A directive consists of
- name
- arguments
- options
- content
The structure is this:
.. name:: arguments
:option: value
content
Function¶
This directive defines a function:
.. function:: spam(eggs)
ham(eggs)
Spam ham ham the are made with a certain number of eggs.
To cross-reference you can use:
method_name()
with:meth:`method_name`
class_name
with:class:`class_name`
function_name()
with:func:`function_name`
For example with :func:`spam`
one can refernce
the above functions spam()
or ham()
inside a sentence..
Data¶
To describe global data and constants in a module use this code:
.. data:: number=1000
Describe data.
produces
-
number=1000
Describe data.
Functions with arguments¶
-
send_message
(sender, recipient, message_body[, priority=1])¶ Send a message to a recipient
Parameters: - sender (str) – The person sending the message
- recipient (str) – The recipient of the message
- message_body (str) – The body of the message
- priority (integer or None) – The priority of the message, can be a number 1-5
Returns: the message id
Return type: int
Raises: - ValueError – if the message_body exceeds 160 characters
- TypeError – if the message_body is not a basestring
Math formulas¶
Since Pythagoras, we know that \(a^2 + b^2 = c^2\).
Euler’s identity, equation (1), was elected one of the most beautiful mathematical formulas.
The app module¶
This code:
.. automodule:: app
:members:
:member-order: bysource
Prints the whole app documentation and lists members by source order.
App - there is only one App object - an app has multiple scenes (App.scenes) - an app has one current scene (App.scene) - an app has one window to draw in (App.screen)
Scene
- a scene has multiple nodes (App.scene.nodes)
- nodes are ordered: the last in the list is displayed last
- the node which is clicked becomes active
- the active node becomes the top node
- the active node has focus (App.scene.focus)
- TAB and shift-TAB select the next node
Node (object)
- nodes have default position and size (pos, size)
- nodes are automatically placed at creation (dir, gap)
- nodes inherit options (color, size, …) from the previous object
A Node object has the following properties
- clickable: mouse-click has effect
- movable: can be moved (mouse, arrow-keys)
- visible: is drawn
- has focus
Debug
- print events to console (cmd+E)
- display node label (cmd+L)
- display outline (cmd+O)
-
class
app.
App
(size=(640, 240), shortcuts={})[source]¶ Create a single-window app with multiple scenes having multiple objects.
-
class
app.
Scene
(caption='Pygame', remember=True, **options)[source]¶ Create a new scene and initialize the node options.
-
class
app.
Text
(text='Text', **options)[source]¶ Create a text object horizontal and vertical alignement.
-
class
app.
EditableTextObj
(text='Text', cmd='', **options)[source]¶ Create keyboard and mouse-editable text with cursor and selection.
-
class
app.
Board
(**options)[source]¶ Draw a mxn board grid with m lines and n columns. m, n number of cells (row, col) i, j index of cell (row, col) dx, dy size of cell Num numeric matrix Num0 initial numeric matrix Col color matrix
Glossary¶
- reStructuredText
- reStructedText is ligh-weight markup langage.