doc/examples/index.txt

   1 .. -*- rst-mode -*-
   2
   3 Examples
   4 ========
   5
   6 The following examples illustrate use cases for "literate programming with
   7 PyLit".
   8
   9 Generally, the literate source will not substitute a user guide, but can
  10 serve as base documentation as well as reference.
  11
  12 The text parts can be used to structure the document, for additional
  13 explanations, documentation of variants and discussion why a specific
  14 approach was chosen.
  15
  16
  17 pylit.py
  18 --------
  19
  20 .. toctree::
  21   :maxdepth: 2
  22
  23   pylit.py
  24
  25
  26 Python Modules
  27 --------------
  28
  29 Typically, most of a Python module's documentation is in docstrings.
  30 Currently, docstrings are treated as code parts by PyLit.
  31
  32 However, literate comments can be used to add structure and documentation
  33 that is not intended for the end user of a module but for people trying to
  34 maintain or extend it (including the original author).
  35
  36 .. toctree::
  37   :maxdepth: 2
  38
  39   99bottles.py
  40   simplestates.py
  41
  42
  43 Doctests
  44 --------
  45
  46 Python's `doctest`_ module runs tests on usage examples.
  47 However, running ``doctest`` on the code source will only run doctests
  48 within docstrings. In contrast, ``pylit --doctest`` will detect all
  49 doctests, in docstrings as well as in text blocks.
  50
  51 This way, the docstrings can be kept concise while comprehensive tests can
  52 be placed in the code file without taking up precious resources and loading
  53 time (as they will be stripped from the byte-compiled module).
  54
  55 .. toctree::
  56    :maxdepth: 1
  57
  58    literate-doctests
  59    testfile_literate.py
  60    testmod_literate.py
  61
  62 .. _doctest: http://docs.python.org/library/doctest.html
  63
  64 Test Scripts
  65 ------------
  66
  67 Test suites are a good example for the advantages of literate programming.
  68 Documenting the rationale and design as well as test considerations can help
  69 a lot when maintaining and extending the tests.
  70
  71 The following unit test modules are tested using the nose_ unit
  72 test discovery & execution framework. (They should be compatible to
  73 `py.test`_.)
  74
  75 .. _nose: http://somethingaboutorange.com/mrl/projects/nose/
  76 .. _py.test: https://docs.pytest.org
  77
  78 .. toctree::
  79   :maxdepth: 2
  80
  81   pylit_test.py
  82   simplestates_test.py
  83   iterqueue_test.py
  84   iterqueue_speed_test.py
  85
  86
  87 Articles and Tutorials
  88 ----------------------
  89
  90 This survey of the various options and attempts to extend an iterator with
  91 methods for `peek`, `pushback` or `test of emptiness` is also a Python
  92 module defining several examples of such rich iterators.
  93
  94 .. toctree::
  95   :maxdepth: 1
  96
  97   iterqueue.py
  98
  99
 100 LaTeX Packages
 101 --------------
 102
 103 The "orthogonal" syntax of reStructuredText and LaTeX makes the documentation
 104 of a LaTeX package in the source document far more readable than using LaTeX
 105 markup.
 106
 107 .. toctree::
 108   :maxdepth: 2
 109
 110   listings-python-options.sty
 111   listings-tex-options.sty
 112   palatino-helvetica-courier.sty
 113
 114 * isomath_ (PDF__): Math for scientists
 115
 116   + LaTeX package for typesetting math according to International
 117     Standard ISO 31 `Quantities and units`.
 118
 119 __ ftp://dante.ctan.org/tex-archive/macros/latex/contrib/isomath/isomath.sty.pdf
 120
 121 Sources:
 122
 123 * listings-python-options.sty_, listings-tex-options.sty_,
 124   palatino-helvetica-courier.sty_
 125 * isomath.sty_, isomath.sty.txt_.
 126
 127 .. _listings-python-options.sty:
 128    http://docutils.sf.net/sandbox/stylesheets/listings-python-options.sty
 129 .. _listings-tex-options.sty:
 130    http://docutils.sf.net/sandbox/stylesheets/listings-tex-options.sty
 131 .. _palatino-helvetica-courier.sty:
 132    http://docutils.sf.net/sandbox/stylesheets/palatino-helvetica-courier.sty
 133 .. _isomath:
 134    http://dante.ctan.org/CTAN/macros/latex/contrib/isomath/isomath.sty.html
 135 .. _isomath.sty:
 136    ftp://dante.ctan.org/tex-archive/macros/latex/contrib/isomath/isomath.sty
 137 .. _isomath.sty.txt:
 138    ftp://dante.ctan.org/tex-archive/macros/latex/contrib/isomath/isomath.sty.txt
 139
 140
 141 CSS Style Sheets
 142 ----------------
 143
 144 Also cascading style sheets can gain from being made literate documents.
 145
 146 .. toctree::
 147   :maxdepth: 1
 148
 149   pygments-default.css
 150
 151
 152 Configuration Files
 153 -------------------
 154
 155 Generating a template as well as user documentation from the same
 156 source helps to keep them synchronised:
 157
 158 .. toctree::
 159   :maxdepth: 1
 160
 161   conf.py