introduction to restructuredtext
DESCRIPTION
It is the slides of the share at PyHUG on 2013/10/31.TRANSCRIPT
![Page 1: Introduction to reStructuredText](https://reader034.vdocuments.us/reader034/viewer/2022042512/54b6f1514a79590d5e8b4589/html5/thumbnails/1.jpg)
Introduction to reStructuredText
Mosky
![Page 2: Introduction to reStructuredText](https://reader034.vdocuments.us/reader034/viewer/2022042512/54b6f1514a79590d5e8b4589/html5/thumbnails/2.jpg)
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
![Page 3: Introduction to reStructuredText](https://reader034.vdocuments.us/reader034/viewer/2022042512/54b6f1514a79590d5e8b4589/html5/thumbnails/3.jpg)
reStructuredText
• reST, RST
• no REST(Representational State Transfer)
• A part of Python's Docutils
• A Lightweight Markup Language(like Markdown)
![Page 4: Introduction to reStructuredText](https://reader034.vdocuments.us/reader034/viewer/2022042512/54b6f1514a79590d5e8b4589/html5/thumbnails/4.jpg)
Installation
![Page 5: Introduction to reStructuredText](https://reader034.vdocuments.us/reader034/viewer/2022042512/54b6f1514a79590d5e8b4589/html5/thumbnails/5.jpg)
Installation• Test if you already have:
• rst2html.py --version
• If you have pip:
• pip install docutils
• Other:
• http://docutils.sourceforge.net/README.html#installation
![Page 6: Introduction to reStructuredText](https://reader034.vdocuments.us/reader034/viewer/2022042512/54b6f1514a79590d5e8b4589/html5/thumbnails/6.jpg)
Markups
![Page 7: Introduction to reStructuredText](https://reader034.vdocuments.us/reader034/viewer/2022042512/54b6f1514a79590d5e8b4589/html5/thumbnails/7.jpg)
Markups
• Implicit Markups
• Explicit Markups
![Page 8: Introduction to reStructuredText](https://reader034.vdocuments.us/reader034/viewer/2022042512/54b6f1514a79590d5e8b4589/html5/thumbnails/8.jpg)
Implicit Markups• Inline Markups
• Section & Paragraph
• Lists (5 types)
• Blocks (4 types)
• Table (2 styles)
• Transition
• (Formatting Markups)
![Page 9: Introduction to reStructuredText](https://reader034.vdocuments.us/reader034/viewer/2022042512/54b6f1514a79590d5e8b4589/html5/thumbnails/9.jpg)
Explicit Markups• Footnotes (2 types)
• Citation
• Hyperlink Targets (4 t.)
• Directive
• Substitution
• Comment
• (Dot-Dot Markups)
![Page 10: Introduction to reStructuredText](https://reader034.vdocuments.us/reader034/viewer/2022042512/54b6f1514a79590d5e8b4589/html5/thumbnails/10.jpg)
Implicit Markups
![Page 11: Introduction to reStructuredText](https://reader034.vdocuments.us/reader034/viewer/2022042512/54b6f1514a79590d5e8b4589/html5/thumbnails/11.jpg)
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: \
![Page 12: Introduction to reStructuredText](https://reader034.vdocuments.us/reader034/viewer/2022042512/54b6f1514a79590d5e8b4589/html5/thumbnails/12.jpg)
Section & Paragraph=====Title=====
Subtitle--------
The first paragraph.
The second paragraph.
=-`:'"~^_*+#<>
Title
Subtitle
The first paragraph.
The second paragraph.
=-`:'"~^_*+#<>
![Page 13: Introduction to reStructuredText](https://reader034.vdocuments.us/reader034/viewer/2022042512/54b6f1514a79590d5e8b4589/html5/thumbnails/13.jpg)
Lists
• Enumerated List
• Bullet List
• Definition List
• Option List
![Page 14: Introduction to reStructuredText](https://reader034.vdocuments.us/reader034/viewer/2022042512/54b6f1514a79590d5e8b4589/html5/thumbnails/14.jpg)
Enumerated ListA 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.
![Page 15: Introduction to reStructuredText](https://reader034.vdocuments.us/reader034/viewer/2022042512/54b6f1514a79590d5e8b4589/html5/thumbnails/15.jpg)
Bullet ListA 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.
![Page 16: Introduction to reStructuredText](https://reader034.vdocuments.us/reader034/viewer/2022042512/54b6f1514a79590d5e8b4589/html5/thumbnails/16.jpg)
Definition ListA definition list:
Python Python is a programming language.
reStructuredText reStructuredText is a markup syntax and parser system.
A Definition List:
PythonPython is a programming language.
reStructuredTextreStructuredText is a markup syntax and parser system.
![Page 17: Introduction to reStructuredText](https://reader034.vdocuments.us/reader034/viewer/2022042512/54b6f1514a79590d5e8b4589/html5/thumbnails/17.jpg)
Field List:Author: Mosky Liu
Thanks the Quickref
:Date: 2013/10/29
Author: Mosky LiuThanks the Quickref
Date: 2013/10/29
![Page 18: Introduction to reStructuredText](https://reader034.vdocuments.us/reader034/viewer/2022042512/54b6f1514a79590d5e8b4589/html5/thumbnails/18.jpg)
Option List-a opt and long desc-b file opt with arg--long long opt
-a-b--long
opt and long decopt with arglong opt
![Page 19: Introduction to reStructuredText](https://reader034.vdocuments.us/reader034/viewer/2022042512/54b6f1514a79590d5e8b4589/html5/thumbnails/19.jpg)
Blocks
• Literal Block
• Line Block
• Block Quote
• Doctest Block
![Page 20: Introduction to reStructuredText](https://reader034.vdocuments.us/reader034/viewer/2022042512/54b6f1514a79590d5e8b4589/html5/thumbnails/20.jpg)
Literal BlockA literal block:
::
Everything will be kept here.
Out of the literal block.
A literal block:
Everything will bekept here.
Out of the literal block.
![Page 21: Introduction to reStructuredText](https://reader034.vdocuments.us/reader034/viewer/2022042512/54b6f1514a79590d5e8b4589/html5/thumbnails/21.jpg)
Literal BlockA literal block: ::
Everything will be kept here.
Out of the literal block.
A literal block:
Everything will bekept here.
Out of the literal block.
![Page 22: Introduction to reStructuredText](https://reader034.vdocuments.us/reader034/viewer/2022042512/54b6f1514a79590d5e8b4589/html5/thumbnails/22.jpg)
Line BlockA line block:
| Line breaks and| initial indents| are preserved.
A line block:
Line breaks and initial indentsare preserved.
![Page 23: Introduction to reStructuredText](https://reader034.vdocuments.us/reader034/viewer/2022042512/54b6f1514a79590d5e8b4589/html5/thumbnails/23.jpg)
Block QuoteBlock quotes are just:
Indented paragraphs.
Block quotes are just:
Indented paragraphs.
![Page 24: Introduction to reStructuredText](https://reader034.vdocuments.us/reader034/viewer/2022042512/54b6f1514a79590d5e8b4589/html5/thumbnails/24.jpg)
Doctest BlockA doctest block:
>>> print "Hey!" Hey!
A doctest block:
>>> print "Hey!" Hey!
![Page 25: Introduction to reStructuredText](https://reader034.vdocuments.us/reader034/viewer/2022042512/54b6f1514a79590d5e8b4589/html5/thumbnails/25.jpg)
Table
• Grid Table
• Simple Table
• These are styles of table.
![Page 26: Introduction to reStructuredText](https://reader034.vdocuments.us/reader034/viewer/2022042512/54b6f1514a79590d5e8b4589/html5/thumbnails/26.jpg)
Grid TableA grid table:
+----------+----------+| Header 1 | Header 2 |+==========+==========+| Column 1 | Column 2 |+----------+----------+| Spanned Column |+---------------------+
A grid table:
Header 1 Header 2
Column 1 Column 2
Spanned ColumnSpanned Column
![Page 27: Introduction to reStructuredText](https://reader034.vdocuments.us/reader034/viewer/2022042512/54b6f1514a79590d5e8b4589/html5/thumbnails/27.jpg)
Simple TableA simple table:
======== ========Header 1 Header 2======== ========Column 1 Column 2-------- --------Spanned Column==================
A simple table:
Header 1 Header 2
Column 1 Column 2
Spanned ColumnSpanned Column
![Page 28: Introduction to reStructuredText](https://reader034.vdocuments.us/reader034/viewer/2022042512/54b6f1514a79590d5e8b4589/html5/thumbnails/28.jpg)
Transition4 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.
![Page 29: Introduction to reStructuredText](https://reader034.vdocuments.us/reader034/viewer/2022042512/54b6f1514a79590d5e8b4589/html5/thumbnails/29.jpg)
Explicit Markups
![Page 30: Introduction to reStructuredText](https://reader034.vdocuments.us/reader034/viewer/2022042512/54b6f1514a79590d5e8b4589/html5/thumbnails/30.jpg)
Footnotes
• Numerical Footnote
• Symbol Footnote
![Page 31: Introduction to reStructuredText](https://reader034.vdocuments.us/reader034/viewer/2022042512/54b6f1514a79590d5e8b4589/html5/thumbnails/31.jpg)
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/
![Page 32: Introduction to reStructuredText](https://reader034.vdocuments.us/reader034/viewer/2022042512/54b6f1514a79590d5e8b4589/html5/thumbnails/32.jpg)
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/
![Page 33: Introduction to reStructuredText](https://reader034.vdocuments.us/reader034/viewer/2022042512/54b6f1514a79590d5e8b4589/html5/thumbnails/33.jpg)
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/
![Page 34: Introduction to reStructuredText](https://reader034.vdocuments.us/reader034/viewer/2022042512/54b6f1514a79590d5e8b4589/html5/thumbnails/34.jpg)
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/
![Page 35: Introduction to reStructuredText](https://reader034.vdocuments.us/reader034/viewer/2022042512/54b6f1514a79590d5e8b4589/html5/thumbnails/35.jpg)
Hyperlink Targets
• External
• Internal
• Indirect
• Implicit
![Page 36: Introduction to reStructuredText](https://reader034.vdocuments.us/reader034/viewer/2022042512/54b6f1514a79590d5e8b4589/html5/thumbnails/36.jpg)
ExternalHyperlink 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.
![Page 37: Introduction to reStructuredText](https://reader034.vdocuments.us/reader034/viewer/2022042512/54b6f1514a79590d5e8b4589/html5/thumbnails/37.jpg)
InternalHyperlink 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.
![Page 38: Introduction to reStructuredText](https://reader034.vdocuments.us/reader034/viewer/2022042512/54b6f1514a79590d5e8b4589/html5/thumbnails/38.jpg)
IndirectHyperlink Target
Python_ is `my favourite programming language`__.
.. _Python: http://www.python.org/
__ Python_
Python is my favourite programming language.
![Page 39: Introduction to reStructuredText](https://reader034.vdocuments.us/reader034/viewer/2022042512/54b6f1514a79590d5e8b4589/html5/thumbnails/39.jpg)
ImplicitHyperlink Target
Titles are targets, too =======================
Implict references, like `Titles are targets, too`_.
Title are targets, too
Implict references, like Titles are targets, too.
![Page 40: Introduction to reStructuredText](https://reader034.vdocuments.us/reader034/viewer/2022042512/54b6f1514a79590d5e8b4589/html5/thumbnails/40.jpg)
Directive
PyHUG's logo:
.. image:: pyhug.jpg
PyHUG's logo:
![Page 41: Introduction to reStructuredText](https://reader034.vdocuments.us/reader034/viewer/2022042512/54b6f1514a79590d5e8b4589/html5/thumbnails/41.jpg)
Substitution
PyHUG's logo: |pyhug|
.. |pyhug| image:: pyhug.jpg
PyHUG's logo:
![Page 42: Introduction to reStructuredText](https://reader034.vdocuments.us/reader034/viewer/2022042512/54b6f1514a79590d5e8b4589/html5/thumbnails/42.jpg)
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.
![Page 43: Introduction to reStructuredText](https://reader034.vdocuments.us/reader034/viewer/2022042512/54b6f1514a79590d5e8b4589/html5/thumbnails/43.jpg)
Links
![Page 44: Introduction to reStructuredText](https://reader034.vdocuments.us/reader034/viewer/2022042512/54b6f1514a79590d5e8b4589/html5/thumbnails/44.jpg)
Links
• Quick reStructuredTexthttp://docutils.sourceforge.net/docs/user/rst/quickref.html
• reStructuredText Directiveshttp://docutils.sourceforge.net/docs/ref/rst/directives.html
• Sphinxhttp://sphinx-doc.org/
• Markdownhttp://markdown.tw/
![Page 45: Introduction to reStructuredText](https://reader034.vdocuments.us/reader034/viewer/2022042512/54b6f1514a79590d5e8b4589/html5/thumbnails/45.jpg)
Any Question?