adv_py: Add notes, slides and a few exercises.

1 files changed, 276 insertions, 0 deletions

diff --git a/advanced_python/rst.rst b/advanced_python/rst.rst
new file mode 100644
index 0000000..bf8e73d
--- /dev/null
+++ b/advanced_python/rst.rst
@@ -0,0 +1,276 @@
+====
+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
+