Introduction to
reStructuredText
Mosky
Mosky
•

A Python engineer at Pinkoi

•

An author of some Python packages
(MoSQL, Clime, ...)

•

A speaker at some confe...
reStructuredText
•

reST, RST

•

no REST
(Representational State Transfer)

•

A part of Python's Docutils

•

A Lightwei...
Installation
Installation
•

Test if you already have:

•
•

If you have pip:

•
•

rst2html.py --version

pip install docutils

Other:...
Markups
Markups

•

Implicit Markups

•

Explicit Markups
Implicit Markups
•

Inline Markups

•

Blocks (4 types)

•

Section & Paragraph

•

Table (2 styles)

•

Lists (5 types)

...
Explicit Markups
•

Footnotes (2 types)

•

Directive

•

Citation

•

Substitution

•

Hyperlink Targets (4 t.)

•

Comme...
Implicit Markups
Inline Markups
*emphasis*

emphasis

**strong emphasis**

strong emphasis

`interpreted text`

interpreted text

``inline ...
Section & Paragraph
=====
Title
=====
Subtitle
--------

Title
Subtitle
The first paragraph.

The first paragraph.

The sec...
Lists
•

Enumerated List

•

Bullet List

•

Definition List

•

Option List
Enumerated List
A enumerated list:

A enumerated list:

3. The first item.
4. The second item.
#. The third item.

3. The ...
Bullet List
A bullet list:
- This is item 1
- This is item 2
- "-", "*" or "+".
Continuing text must
be aligned.
The two b...
Definition List
A definition list:

A Definition List:

Python
Python is a
programming language.

Python
Python is a program...
Field List
:Author:
Mosky Liu
Thanks the Quickref
:Date: 2013/10/29

Mosky Liu
Author:
Thanks the Quickref
Date:
2013/10/2...
Option List
-a     

opt
and long desc
-b file  opt with arg
--long   long opt

-a
-b
--long

opt and long dec
opt with ar...
Blocks
•

Literal Block

•

Line Block

•

Block Quote

•

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

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

A literal block:
Everything w...
Line Block
A line block:

A line block:

| Line breaks and
|
initial indents
| are preserved.

Line breaks and
initial ind...
Block Quote
Block quotes are just:
    Indented paragraphs.

Block quotes are just:
Indented paragraphs.
Doctest Block
A doctest block:

A doctest block:

>>> print "Hey!"
Hey!

>>> print "Hey!"
Hey!
Table
•

Grid Table

•

Simple Table

•

These are styles of table.
Grid Table
A grid table:
+----------+----------+
| Header 1 | Header 2 |
+==========+==========+
| Column 1 | Column 2 |
+...
Simple Table
A simple table:
======== ========
Header 1 Header 2
======== ========
Column 1 Column 2
-------- -------Spann...
Transition
4 or more punctuation
chars.
---No begin or end a sect
or doc.

4 or more punctuation
chars.
No begin or end a ...
Explicit Markups
Footnotes

•

Numerical Footnote

•

Symbol Footnote
Numerical Footnote
PyHUG [1]_ and Taipei.py [2]_ are both the Python
user groups in Taiwan.
.. [1] http://www.meetup.com/p...
Numerical Footnote
PyHUG [#]_ and Taipei.py [#]_ are both the Python
user groups in Taiwan.
.. [#] http://www.meetup.com/p...
Symbol Footnote
PyHUG [*]_ and Taipei.py [*]_ are both the Python
user groups in Taiwan.
.. [*] http://www.meetup.com/pyth...
Citation
[PyHUG]_ and [Taipei.py]_ are both the Python user
groups in Taiwan.
.. [PyHUG]
http://www.meetup.com/pythonhug/
...
Hyperlink Targets
•

External

•

Internal

•

Indirect

•

Implicit
External
Hyperlink Target
PyHUG_ and Taipei.py_ are both the `Python <http://
python.org/>`_ user groups in Taiwan.
.. _Py...
Internal
Hyperlink Target
PyHUG_ and Taipei.py_ are both the Python user groups
in Taiwan.
.. _PyHUG:
PyHUG is ...
.. _Tai...
Indirect
Hyperlink Target
Python_ is `my favourite programming language`__.
.. _Python: http://www.python.org/
__ Python_
...
Implicit
Hyperlink Target
Titles are targets, too
=======================
Implict references, like `Titles are targets, to...
Directive
PyHUG's logo:
.. image:: pyhug.jpg

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

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

PyHUG an...
Links
Links
•

Quick reStructuredText
http://docutils.sourceforge.net/docs/user/rst/quickref.html

•

reStructuredText Directive...
Any Question?
Upcoming SlideShare
Loading in …5
×

Introduction to reStructuredText

1,272 views

Published on

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

Published in: Software
2 Comments
3 Likes
Statistics
Notes
No Downloads
Views
Total views
1,272
On SlideShare
0
From Embeds
0
Number of Embeds
2
Actions
Shares
0
Downloads
19
Comments
2
Likes
3
Embeds 0
No embeds

No notes for slide

Introduction to reStructuredText

  1. 1. Introduction to reStructuredText Mosky
  2. 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. 3. reStructuredText • reST, RST • no REST (Representational State Transfer) • A part of Python's Docutils • A Lightweight Markup Language (like Markdown)
  4. 4. Installation
  5. 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. 6. Markups
  7. 7. Markups • Implicit Markups • Explicit Markups
  8. 8. Implicit Markups • Inline Markups • Blocks (4 types) • Section & Paragraph • Table (2 styles) • Lists (5 types) • Transition • (Formatting Markups)
  9. 9. Explicit Markups • Footnotes (2 types) • Directive • Citation • Substitution • Hyperlink Targets (4 t.) • Comment • (Dot-Dot Markups)
  10. 10. Implicit Markups
  11. 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. 12. Section & Paragraph ===== Title ===== Subtitle -------- Title Subtitle The first paragraph. The first paragraph. The second paragraph. The second paragraph. =-`:'"~^_*+#<> =-`:'"~^_*+#<>
  13. 13. Lists • Enumerated List • Bullet List • Definition List • Option List
  14. 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. 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. 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. 17. Field List :Author: Mosky Liu Thanks the Quickref :Date: 2013/10/29 Mosky Liu Author: Thanks the Quickref Date: 2013/10/29
  18. 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. 19. Blocks • Literal Block • Line Block • Block Quote • Doctest Block
  20. 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. 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. 22. Line Block A line block: A line block: | Line breaks and | initial indents | are preserved. Line breaks and initial indents are preserved.
  23. 23. Block Quote Block quotes are just:     Indented paragraphs. Block quotes are just: Indented paragraphs.
  24. 24. Doctest Block A doctest block: A doctest block: >>> print "Hey!" Hey! >>> print "Hey!" Hey!
  25. 25. Table • Grid Table • Simple Table • These are styles of table.
  26. 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. 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. 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. 29. Explicit Markups
  30. 30. Footnotes • Numerical Footnote • Symbol Footnote
  31. 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. 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. 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. 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. 35. Hyperlink Targets • External • Internal • Indirect • Implicit
  36. 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. 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. 38. Indirect Hyperlink Target Python_ is `my favourite programming language`__. .. _Python: http://www.python.org/ __ Python_ Python is my favourite programming language.
  39. 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. 40. Directive PyHUG's logo: .. image:: pyhug.jpg PyHUG's logo:
  41. 41. Substitution PyHUG's logo: |pyhug| .. |pyhug| image:: pyhug.jpg PyHUG's logo:
  42. 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. 43. Links
  44. 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. 45. Any Question?

×