rstdocs/usage.txt

   1 .. -*- rst-mode -*-
   2
   3 Usage
   4 =====
   5
   6 Command line use
   7 ----------------
   8
   9 ::
  10
  11    #> python pylit.py [options] INFILE [OUTFILE]
  12
  13 ..
  14
  15   Convert between (reStructured) text source with embedded code, and code
  16   source with embedded documentation (comment blocks)
  17
  18   The special file name '-' stands for standard in and output.
  19
  20 Find more details in the tutorial_.
  21
  22 .. _tutorial: tutorial/index.html
  23
  24 Options
  25 ~~~~~~~
  26
  27   --version             show program's version number and exit
  28   -h, --help            show this help message and exit
  29   -c, --code2txt        convert code source to text source
  30   -t, --txt2code        convert text source to code source
  31   --language=LANGUAGE   use LANGUAGE native comment style
  32   --comment-string=COMMENT_STRING
  33                         documentation block marker in code source (including
  34                         trailing whitespace, default: language dependent)
  35   -m CODE_BLOCK_MARKER, --code-block-marker=CODE_BLOCK_MARKER
  36                         syntax token starting a code block. (default '::')
  37   --codeindent=CODEINDENT
  38                         Number of spaces to indent code blocks with text2code
  39                         (default 2)
  40   --overwrite=OVERWRITE
  41                         overwrite output file (default 'update')
  42   --replace             move infile to a backup copy (appending '~')
  43   -s, --strip           "export" by stripping documentation or code
  44   -d, --diff            test for differences to existing file
  45   --doctest             run doctest.testfile() on the text version
  46   -e, --execute         execute code (Python only)
  47
  48
  49 Filename Extensions
  50 ~~~~~~~~~~~~~~~~~~~
  51
  52 By default ``.txt`` will be appended for literate code and stripped by the
  53 conversion to executable code. I.e. for a Python module `foo`:
  54
  55 * the code source is called ``foo.py``
  56 * the text source is called ``foo.py.txt``
  57 * the HTML rendering is called ``foo.py.html``
  58
  59 See also `filename extensions <filename-extensions.html>`_.
  60
  61 Programmatic use
  62 ----------------
  63
  64 If pylit.py is in the Python Module Path, it can be imported and used from
  65 other Python programs. The simplest example is the executable wrapper script
  66 pylit that can also be used for customisation_:
  67
  68 .. include:: download/pylit
  69    :literal:
  70
  71 For more details see e.g. the `helper functions`_ in the `literate source`_.
  72
  73 .. _helper functions: examples/pylit.py.html#helper-functions
  74 .. _literate source: examples/pylit.py.html
  75 .. _pylit: download/pylit
  76
  77 Customisation
  78 -------------
  79
  80 Customisation is possible by overwriting `default values`_  in a wrapper
  81 script like pylit_, e.g. ::
  82
  83   #!/usr/bin/env python
  84
  85   import pylit
  86
  87   pylit.defaults.code_block_marker = '.. code-block:: python'
  88   pylit.defaults.comment_string = "## "
  89   pylit.defaults.codeindent = 4
  90   defaults.text_extensions = [".rst"]
  91
  92   pylit.main()
  93
  94 To overwrite the "intelligent guesses" by PylitOptions_ and command line
  95 options, pass the option as argument to `pylit.main()`_, e.g.::
  96
  97   #!/usr/bin/env python
  98
  99   import pylit
 100   pylit.main(comment_string = "## ")
 101
 102
 103 .. _default values: examples/pylit.py.html#defaults
 104 .. _PylitOptions:  examples/pylit.py.html#PylitOptions
 105 .. _pylit.main():  examples/pylit.py.html#main