Upgrade to Pro — share decks privately, control downloads, hide ads and more …

Introduction to reStructuredText

Mosky Liu
October 31, 2013

Introduction to reStructuredText

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

Mosky Liu

October 31, 2013
Tweet

More Decks by Mosky Liu

Other Decks in Programming

Transcript

  1. Introduction to
    reStructuredText
    Mosky

    View full-size slide

  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

    View full-size slide

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

    View full-size slide

  4. Installation

    View full-size slide

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

    View full-size slide

  6. Markups
    • Implicit Markups
    • Explicit Markups

    View full-size slide

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

    View full-size slide

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

    View full-size slide

  9. Implicit Markups

    View full-size slide

  10. 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: \

    View full-size slide

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

    View full-size slide

  12. Lists
    • Enumerated List
    • Bullet List
    • Definition List
    • Option List

    View full-size slide

  13. 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.

    View full-size slide

  14. 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.

    View full-size slide

  15. 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.

    View full-size slide

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

    View full-size slide

  17. 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

    View full-size slide

  18. Blocks
    • Literal Block
    • Line Block
    • Block Quote
    • Doctest Block

    View full-size slide

  19. 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.

    View full-size slide

  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.

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

  25. 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

    View full-size slide

  26. 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

    View full-size slide

  27. 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.

    View full-size slide

  28. Explicit Markups

    View full-size slide

  29. Footnotes
    • Numerical Footnote
    • Symbol Footnote

    View full-size slide

  30. 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/

    View full-size slide

  31. 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/

    View full-size slide

  32. 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/

    View full-size slide

  33. 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/

    View full-size slide

  34. Hyperlink Targets
    • External
    • Internal
    • Indirect
    • Implicit

    View full-size slide

  35. External
    Hyperlink Target
    PyHUG_ and Taipei.py_ are both the `Python 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.

    View full-size slide

  36. 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.

    View full-size slide

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

    View full-size slide

  38. 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.

    View full-size slide

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

    View full-size slide

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

    View full-size slide

  41. 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.

    View full-size slide

  42. 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/

    View full-size slide

  43. Any Question?

    View full-size slide