It is the slides of the share at PyHUG on 2013/10/31.

1. Introduction to
reStructuredText
Mosky

2. Mosky
•
A Python engineer at Pinkoi
•
An author of some Python packages
(MoSQL, Clime, ...)
•
A speaker at some conferences
(PyCon APAC, PyCon TW, COSCUP, ...)
•
A Python trainer
•
mosky.tw

3. reStructuredText
•
reST, RST
•
no REST
(Representational State Transfer)
•
A part of Python's Docutils
•
A Lightweight Markup Language
(like Markdown)

4. Installation

5. Installation
•
Test if you already have:
•
•
If you have pip:
•
•
rst2html.py --version
pip install docutils
Other:
•
http://docutils.sourceforge.net/
README.html#installation

6. Markups

7. Markups
•
Implicit Markups
•
Explicit Markups

8. Implicit Markups
•
Inline Markups
•
Blocks (4 types)
•
Section & Paragraph
•
Table (2 styles)
•
Lists (5 types)
•
Transition
•
(Formatting Markups)

9. Explicit Markups
•
Footnotes (2 types)
•
Directive
•
Citation
•
Substitution
•
Hyperlink Targets (4 t.)
•
Comment
•
(Dot-Dot Markups)

10. Implicit Markups

11. Inline Markups
*emphasis*
emphasis
**strong emphasis**
strong emphasis
`interpreted text`
interpreted text
``inline literal``
inline literal
*escape*, **esacpe**
*escape*, **esacpe**
A backslash literal:
A backslash literal:

12. Section & Paragraph
=====
Title
=====
Subtitle
--------
Title
Subtitle
The first paragraph.
The first paragraph.
The second paragraph.
The second paragraph.
=-`:'"~^_*+#<>
=-`:'"~^_*+#<>

13. Lists
•
Enumerated List
•
Bullet List
•
Definition List
•
Option List

14. Enumerated List
A enumerated list:
A enumerated list:
3. The first item.
4. The second item.
#. The third item.
3. The first item.
4. The second item.
5. The third item.
``1.``, ``A.``, ``I.``,
``(1)``, ``1)`` are also
work.
1., A., I., (1), 1) also
work.

15. Bullet List
A bullet list:
- This is item 1
- This is item 2
- "-", "*" or "+".
Continuing text must
be aligned.
The two blank lines is
required.
A bullet list:
•
•
•
This is item 1
This is item 2
"-", "*" or "+".
Continuing text must be
aligned.
The two blank lines is
required.

16. Definition List
A definition list:
A Definition List:
Python
Python is a
programming language.
Python
Python is a programming
language.
reStructuredText
reStructuredText is a
markup syntax and
parser system.
reStructuredText
reStructuredText is a
markup syntax and
parser system.

17. Field List
:Author:
Mosky Liu
Thanks the Quickref
:Date: 2013/10/29
Mosky Liu
Author:
Thanks the Quickref
Date:
2013/10/29

18. Option List
-a
opt
and long desc
-b file opt with arg
--long long opt
-a
-b
--long
opt and long dec
opt with arg
long opt

19. Blocks
•
Literal Block
•
Line Block
•
Block Quote
•
Doctest Block

20. Literal Block
A literal block:
::
Everything will be
kept here.
Out of the literal
block.
A literal block:
Everything will be
kept here.
Out of the literal block.

21. Literal Block
A literal block: ::
Everything will be
kept here.
Out of the literal
block.
A literal block:
Everything will be
kept here.
Out of the literal block.

22. Line Block
A line block:
A line block:
| Line breaks and
|
initial indents
| are preserved.
Line breaks and
initial indents
are preserved.

23. Block Quote
Block quotes are just:
Indented paragraphs.
Block quotes are just:
Indented paragraphs.

24. Doctest Block
A doctest block:
A doctest block:
>>> print "Hey!"
Hey!
>>> print "Hey!"
Hey!

25. Table
•
Grid Table
•
Simple Table
•
These are styles of table.

26. Grid Table
A grid table:
+----------+----------+
| Header 1 | Header 2 |
+==========+==========+
| Column 1 | Column 2 |
+----------+----------+
| Spanned Column
|
+---------------------+
A grid table:
Header 1
Column 1
Header 2
Column 2
Spanned Column

27. Simple Table
A simple table:
======== ========
Header 1 Header 2
======== ========
Column 1 Column 2
-------- -------Spanned Column
==================
A simple table:
Header 1
Column 1
Header 2
Column 2
Spanned Column

28. Transition
4 or more punctuation
chars.
---No begin or end a sect
or doc.
4 or more punctuation
chars.
No begin or end a sect
or doc.

29. Explicit Markups

30. Footnotes
•
Numerical Footnote
•
Symbol Footnote

31. Numerical Footnote
PyHUG [1]_ and Taipei.py [2]_ are both the Python
user groups in Taiwan.
.. [1] http://www.meetup.com/pythonhug/
.. [2] http://taipei.python.org.tw/
PyHUG [1] and Taiepi.py [2] both are the Python user groups in
Taiwan.
[1] http://www.meetup.com/pythonhug/
[2] http://taipei.python.org.tw/

32. Numerical Footnote
PyHUG [#]_ and Taipei.py [#]_ are both the Python
user groups in Taiwan.
.. [#] http://www.meetup.com/pythonhug/
.. [#] http://taipei.python.org.tw/
PyHUG [1] and Taiepi.py [2] both are the Python user groups in
Taiwan.
[1] http://www.meetup.com/pythonhug/
[2] http://taipei.python.org.tw/

33. Symbol Footnote
PyHUG [*]_ and Taipei.py [*]_ are both the Python
user groups in Taiwan.
.. [*] http://www.meetup.com/pythonhug/
.. [*] http://taipei.python.org.tw/
PyHUG [*] and Taiepi.py [†] both are the Python user groups in
Taiwan.
[*] http://www.meetup.com/pythonhug/
[†] http://taipei.python.org.tw/

34. Citation
[PyHUG]_ and [Taipei.py]_ are both the Python user
groups in Taiwan.
.. [PyHUG]
http://www.meetup.com/pythonhug/
.. [Taiepi.py] http://taipei.python.org.tw/
[PyHUG] and [Taiepi.py] both are the Python user groups in
Taiwan.
[PyHUG] http://www.meetup.com/pythonhug/
[Taipei.py] http://taipei.python.org.tw/

35. Hyperlink Targets
•
External
•
Internal
•
Indirect
•
Implicit

36. External
Hyperlink Target
PyHUG_ and Taipei.py_ are both the `Python <http://
python.org/>`_ user groups in Taiwan.
.. _PyHUG:
http://www.meetup.com/pythonhug/
.. _Taiepi.py: http://taipei.python.org.tw/
PyHUG and Taiepi.py both are the Python user groups in
Taiwan.

37. Internal
Hyperlink Target
PyHUG_ and Taipei.py_ are both the Python user groups
in Taiwan.
.. _PyHUG:
PyHUG is ...
.. _Taiepi.py:
Taipei.py is ...
PyHUG and Taiepi.py both are the Python user groups in
Taiwan.

38. Indirect
Hyperlink Target
Python_ is `my favourite programming language`__.
.. _Python: http://www.python.org/
__ Python_
Python is my favourite programming language.

39. Implicit
Hyperlink Target
Titles are targets, too
=======================
Implict references, like `Titles are targets, too`_.
Title are targets, too
Implict references, like Titles are targets, too.

40. Directive
PyHUG's logo:
.. image:: pyhug.jpg
PyHUG's logo:

41. Substitution
PyHUG's logo: |pyhug|
.. |pyhug| image:: pyhug.jpg
PyHUG's logo:

42. Comment
PyHUG and Taipei.py are both the Python user groups
in Taiwan.
.. TODO: Put Tainan.py in this paragraph.
PyHUG and Taipei.py are both the Python user groups in
Taiwan.

43. Links

44. Links
•
Quick reStructuredText
http://docutils.sourceforge.net/docs/user/rst/quickref.html
•
reStructuredText Directives
http://docutils.sourceforge.net/docs/ref/rst/directives.html
•
Sphinx
http://sphinx-doc.org/
•
Markdown
http://markdown.tw/

45. Any Question?