Tweet
Tweet

Slide 1

Slide 1 text

Introduction to reStructuredText Mosky

Slide 2

Slide 2 text

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

Slide 3

Slide 3 text

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

Slide 4

Slide 4 text

Installation

Slide 5

Slide 5 text

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

Slide 6

Slide 6 text

Markups

Slide 7

Slide 7 text

Markups • Implicit Markups • Explicit Markups

Slide 8

Slide 8 text

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

Slide 9

Slide 9 text

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

Slide 10

Slide 10 text

Implicit Markups

Slide 11

Slide 11 text

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

Slide 12

Slide 12 text

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

Slide 13

Slide 13 text

Lists • Enumerated List • Bullet List • Definition List • Option List

Slide 14

Slide 14 text

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

Slide 15

Slide 15 text

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.

Slide 16

Slide 16 text

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

Slide 17

Slide 17 text

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

Slide 18

Slide 18 text

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

Slide 19

Slide 19 text

Blocks • Literal Block • Line Block • Block Quote • Doctest Block

Slide 20

Slide 20 text

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.

Slide 21

Slide 21 text

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.

Slide 22

Slide 22 text

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

Slide 23

Slide 23 text

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

Slide 24

Slide 24 text

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

Slide 25

Slide 25 text

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

Slide 26

Slide 26 text

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

Slide 27

Slide 27 text

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

Slide 28

Slide 28 text

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.

Slide 29

Slide 29 text

Explicit Markups

Slide 30

Slide 30 text

Footnotes • Numerical Footnote • Symbol Footnote

Slide 31

Slide 31 text

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/

Slide 32

Slide 32 text

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/

Slide 33

Slide 33 text

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/

Slide 34

Slide 34 text

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/

Slide 35

Slide 35 text

Hyperlink Targets • External • Internal • Indirect • Implicit

Slide 36

Slide 36 text

External Hyperlink Target 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.

Slide 37

Slide 37 text

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.

Slide 38

Slide 38 text

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

Slide 39

Slide 39 text

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.

Slide 40

Slide 40 text

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

Slide 41

Slide 41 text

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

Slide 42

Slide 42 text

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.

Slide 43

Slide 43 text

Links

Slide 44

Slide 44 text

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/

Slide 45

Slide 45 text

Any Question?