diff options
Diffstat (limited to 'lecture_notes/advanced_python/rst.rst')
| -rw-r--r-- | lecture_notes/advanced_python/rst.rst | 277 |
1 files changed, 0 insertions, 277 deletions
diff --git a/lecture_notes/advanced_python/rst.rst b/lecture_notes/advanced_python/rst.rst deleted file mode 100644 index fcbd986..0000000 --- a/lecture_notes/advanced_python/rst.rst +++ /dev/null @@ -1,277 +0,0 @@ -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 - |