path: root/advanced_python/rst.rst

ReST
----

----------------------------
The Pythonic way to Document
----------------------------

.. author: FOSSEE
.. date: 2010-07-22 Thu


What is ReST?
-------------

  + Sage Docs - Linear Algebra | Sources
  + ReST is a lightweight markup language. 
  + Developed by the Python community 
  + Heavily used in documentation of Python code 

Why ReST?
---------

  + Highly readable source format. 
  + Easy to learn and write. 
  + Simple yet Powerful markup that can produce html/LaTeX output. 

Tools used
----------

  + You will need python-docutils to compile your ReST documents
::

    sudo apt-get install python-docutils

  + To build websites, look at Sphinx, rest2web, etc. 
  + rst2html doesn't support math. We shall use Sphinx to see how math works
::

    sudo apt-get install python-sphinx

Generating output
-----------------

  + html::

      rst2html source.rst destination.html

  + LaTeX ::

      rst2latex source.rst destination.tex

  + Slide shows ::

      rst2s5 source.rst destination.html

Paragraph
---------

  + The most basic structural element 
  + Just a chunk of text separated by blank lines. 
  + Must begin at the left edge margin. 
  + Indented paragraphs are output as quoted text. 
  + Example ::

      Sage provides standard constructions from linear algebra,
      e.g., the characteristic polynomial, echelon form, trace, 
      decomposition, etc., of a matrix.

Section Headings
----------------

  + Single line of text with adornment 
  + Adornment is underline alone or an over- and underline 
  + ``- = ` :  ' " ~  ^ _ *  + # <  >`` can be used for adornment 
  + All headings with same adornment are at same level 
  + **NOTE**- The over/under line should be at least as long as the heading
    ::

      Linear Algebra
      ==============
  
      Matrix spaces
      -------------
  
      Sparse Linear Algebra
      ---------------------


Text Styles
-----------

     =======================    ====================
      Markup text                Resulting text    
     =======================    ====================
      ``*italics*``              *italics*     
      ``**strong**``             **strong**          
      ````inline literal````     ``inline literal``  
     =======================    ====================



Code Samples
------------

  + To include code, end the prior paragraph with =::= 
  + Code needs to be indented one level 
  + The code block ends, when text falls back to the previous indentation 
  + For instance ::

      For example, each of the following is legal ::

        plot(x, y)         # plot x and y using default line style and color
        plot(x, y, 'bo')   # plot x and y using blue circle markers
        plot(y)            # plot y using x as index array 0..N-1
        plot(y, 'r+')      # ditto, but with red plusses

Math
----

  + ReST in itself doesn't support math 
  + Sphinx has support for math using ~jsmath~ or ~pngmath~ 
      ::

       :math: `3 \times 3`
  
       .. math:: 
  
       \sum_{n=0}^N x_n = y

Lists
-----

  + Three flavors - Enumerated, Bulleted, Definition 
  + Always start as a new paragraph --- preceeded by a new line 
  + Enumerated 

      Number or Letter followed by a =.=,  =)= or surrounded by =( )=.

    ::

      1) Numbers
      #) auto numbered 
      A. Upper case letters
      a) lower case letters
      i) roman numerals
      (I) more roman numerals


Lists ...
---------

  + Bulleted lists

      Start a line with -, + or *

  ::

    * a bullet point using "*"
  
      - a sub-list using "-"
  
        + yet another sub-list
  
      - another item

Lists ...
---------

  + Definition Lists 

    * Consist of Term, and it's definition. 
    * Term is one line phrase; Definition is one or more paragraphs 
    * Definition is indented relative to the term 
    * Blank lines are not allowed between term and it's definition 
  
  what
    Definition lists associate a term with a definition.

Tables
------

  + Simple Tables 

    * Each line is a row. 
    * The table ends with ~=~ 
    * Column Header is specified by using ~=~ 
    * Cells may span columns; ~-~ is used to specify cells spanning columns. 

::
  
  ============ ============ =========== 
   Header 1     Header 2     Header 3   
  ============ ============ =========== 
   body row 1   column 2     column 3   
   body row 2   Cells may span columns. 
  ------------ ------------------------ 
   body row 3   column 2     column 3    
  ============ ============ ===========
  

Tables...
---------

Grid Tables
-----------

::

  +------------+------------+-----------+
  | Header 1   | Header 2   | Header 3  |
  +============+============+===========+
    body row 1   column 2     column 3   
  +------------+------------+-----------+
    body row 2   Cells may span columns. 
  +------------+------------+-----------+
    body row 3   Cells may    - Cells    
  +------------+ span rows.   - contain  
    body row 4                - blocks.  
  +------------+------------+-----------+

Links
-----

  + External links 
  
    Python_ is my favorite programming language. 
  
.. _Python: http://www.python.org/

  + Internal links 

    * To generate a link target, add a label to the location 
  
.. _example:
    * Titles & Section headings automatically produce link targets (in ReST) 
    * Linking to Target 
      + in ReST ::
      
          This is an example_ link.
          A Title
          =======
    
          `A Title`_ automatically generates hyperlink targets.

      + in Sphinx ::
    
         :ref: `This is an example <example>` link.
         This is an :ref: `example` link.
            

Footnotes
---------
::

  This[#]_ gives auto-numbered[#]_ footnotes. 
  
  This[*]_ gives auto-symbol footnotes[*]_.
  
  .. [#] First auto numbered footnote
  .. [#] Second auto numbered footnote
  .. [*] First auto symbol footnote
  .. [*] Second auto symbol footnote



References
----------

    + An Introduction to reStructured Text -- David Goodger
    + Quick reStructuredText
    + reStructuredText-- Bits and Pieces -- Christoph Reller


.. `An Introduction to reStructured Text`: http://docutils.sourceforge.net/docs/ref/rst/introduction.html
.. `Quick reStructuredText`: http://docutils.sourceforge.net/docs/user/rst/quickref.html
.. `reStructuredText-- Bits and Pieces`: http://people.ee.ethz.ch/~creller/web/tricks/reST.html