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?