reST tips & tricks

Code highlighting

Inline code highlight

Usage: :code::code:

Examples:

This is a variable, :url:.
save_as is not used here.
:code:``a = b + c` is interpreted by ReST as: a = b + c

Code-block

1 def hello():
2        print "Hello, World!"

note ___ Pelican implements an extension to reStructuredText to enable support for the <abbr> HTML tag. To use it, write something like this in your post:

This will be turned into HTML (HyperText Markup Language).

This will be turned into HTML (HyperText Markup Language).

Another example: LIFO (last-in, first-out)

Include code with code-include

code-include plugin

It is also possible to include the content of a file as follows:

1 .. code-include:: ../code/python/testing/mymath.py
2         :lexer: python
3         :encoding: utf-8
4         :tab-width: 4
5         :start-line: 3
6         :end-line: 18

1 def multiply(x, y):
2     return x * y

The plugin code-include is part of the Pelican Plugins.

include plugin

From rest-tutorial-1-to-include.rst :

1 .. include:: rest-tutorial-tips-footnotes.rst

reST footnote example

date:	2015-12-02 14:20
tags:	reStructuredText, tutorial
category:	Tutorials
status:	published

beginning of file, rest-tutorial-tips-footnotes.rst

Some text that requires a footnote [1].

this’s in rubric:: directive

[1]	Text of the 2nd footnote.

end of file

Another example :

The follwing is from sample.py file.

“”” here is a dummy documentation “”” import os

def square(x):

”’

short description of the function square longish explanation: returns the square of x: x²

param a: an input argument

returns: x*x

”’

return x*x

assert 4 == square(2)

“”” here is a dummy documentation “”” import os

def square(x):

”’: short description of the function square longish explanation: returns the square of x: x²

param a:	an input argument
returns:	x*x

”’

return x*x

assert 4 == square(2)

Hyperlinks

External links

Simple links - Python

Implicit links, Image and Figure

Internal links

These are internal links

a page, About me
a post, Markdown tutorial in category Tutorials, tagged Markdown.

These are code for the above links:

1 `About me </pages/about-me.html>`_
2 
3 `Markdown tutorial </tutoriials/2015/markdown-tutorial/>`_
4 
5 `Tutorials </category/tutorials/>`_
6 
7 `Markdown </tag/markdown/>`_

Image and Figure

Image

How to show an image?

Figure

Image with a caption:

figure are like images but with a caption and whatever else youwish to add

1 import image

Aliases

Using the logo :

Using this image alias, you can insert it easily in the text |logo|, like this logo . This is especially useful when dealing with complicated code. For instance, in order to include 2 images within a table do as follows:

this is a very long text to include

Text features

Footnotes and citations

Use code [#x] and _[#x]: for a footnote.

Footnotes

Some text that requires a footnote [2] .

Citations

อ้างอิง [TCO2015] (see Bibliography below)

Boxes

The directives that work on this site: note::, warning::, topic::, rubric::, sidebar

Usage of a directive

An example of directive note,

code: .. “note::` This is a note box.

code:	.. “note::` This is a note box.

note

Note

This is a note box.

warning

Warning

note the space between the directive and the text

rubric

rubric n. 1. a title, heading, or the like, in a manuscript, book, statute, etc., written or printed in red or otherwise distinguished from the rest of the text. … —Random House Webster’s College Dictionary, 1991

topic

Your Topic Title

Subsequent indented lines comprise the body of the topic, and are interpreted as body elements.

sidebar

glossary, seealso

Not work .. glossary ::

Open Data: Open Data Handbook (ไทย), https://sites.google.com/site/odhandbook/ and https://sites.google.com/site/od4thl/

Not work .. seealso:: This is a simple seealso note.

Maths and special codes

Math

Basics

MathJAX and Latex.

Usage:

.. ``math::`` in the beginnging of the line.

Examples:

The well known quadratic formula:

x = − b±(√(b² − 4ac))/(2a)

n_offset = ^N − 1∑_k = 0s_kn_k

One can also include maths inline, such as the following:

The power series, (1)/(0!) + (2)/(1!)x + (3)/(2!)x² + (4)/(3!)x³ + … states that…

To include maths inline, use :math:. for example:

:math:`frac{1}{0!}+frac{2}{1!}x+frac{3}{2!}x^2+frac{4}{3!}x^3+…“`

Additional info

Footnotes

[2]	Text of the first footnote.

Bibliography

[TCO2015]

Restructured Text (reST) and Sphinx CheatSheet by Thomas Cokelaer, http://thomas-cokelaer.info/tutorials/sphinx/rest_syntax.html#rst-tutorial