Date post: | 15-Jan-2015 |
Category: |
Technology |
Upload: | mosky-liu |
View: | 607 times |
Download: | 0 times |
Introduction to reStructuredText
Mosky
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
reStructuredText
• reST, RST
• no REST(Representational State Transfer)
• A part of Python's Docutils
• A Lightweight Markup Language(like Markdown)
Installation
Installation• Test if you already have:
• rst2html.py --version
• If you have pip:
• pip install docutils
• Other:
• http://docutils.sourceforge.net/README.html#installation
Markups
Markups
• Implicit Markups
• Explicit Markups
Implicit Markups• Inline Markups
• Section & Paragraph
• Lists (5 types)
• Blocks (4 types)
• Table (2 styles)
• Transition
• (Formatting Markups)
Explicit Markups• Footnotes (2 types)
• Citation
• Hyperlink Targets (4 t.)
• Directive
• Substitution
• Comment
• (Dot-Dot Markups)
Implicit Markups
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: \
Section & Paragraph=====Title=====
Subtitle--------
The first paragraph.
The second paragraph.
=-`:'"~^_*+#<>
Title
Subtitle
The first paragraph.
The second paragraph.
=-`:'"~^_*+#<>
Lists
• Enumerated List
• Bullet List
• Definition List
• Option List
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.
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.
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.
Field List:Author: Mosky Liu
Thanks the Quickref
:Date: 2013/10/29
Author: Mosky LiuThanks the Quickref
Date: 2013/10/29
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
Blocks
• Literal Block
• Line Block
• Block Quote
• Doctest Block
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.
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.
Line BlockA line block:
| Line breaks and| initial indents| are preserved.
A line block:
Line breaks and initial indentsare preserved.
Block QuoteBlock quotes are just:
Indented paragraphs.
Block quotes are just:
Indented paragraphs.
Doctest BlockA doctest block:
>>> print "Hey!" Hey!
A doctest block:
>>> print "Hey!" Hey!
Table
• Grid Table
• Simple Table
• These are styles of table.
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
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
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.
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/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/
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/
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/
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/
Hyperlink Targets
• External
• Internal
• Indirect
• Implicit
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.
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.
IndirectHyperlink Target
Python_ is `my favourite programming language`__.
.. _Python: http://www.python.org/
__ Python_
Python is my favourite programming language.
ImplicitHyperlink Target
Titles are targets, too =======================
Implict references, like `Titles are targets, too`_.
Title are targets, too
Implict references, like Titles are targets, too.
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 and Taipei.py are both the Python user groups in Taiwan.
Links
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/
Any Question?