.. -*- rst-mode -*-

Usage
=====

Command line use
----------------

::

   #> python pylit.py [options] INFILE [OUTFILE]

..

  Convert between (reStructured) text source with embedded code, and code
  source with embedded documentation (comment blocks)

  The special file name '-' stands for standard in and output.

Find more details in the tutorial_.

.. _tutorial: tutorial/index.html

Options
~~~~~~~

  --version             show program's version number and exit
  -h, --help            show this help message and exit
  -c, --code2txt        convert code source to text source
  -t, --txt2code        convert text source to code source
  --language=LANGUAGE   use LANGUAGE native comment style
  --comment-string=COMMENT_STRING
                        documentation block marker in code source (including
                        trailing whitespace, default: language dependent)
  -m CODE_BLOCK_MARKER, --code-block-marker=CODE_BLOCK_MARKER
                        syntax token starting a code block. (default '::')
  --codeindent=CODEINDENT
                        Number of spaces to indent code blocks with text2code
                        (default 2)
  --overwrite=OVERWRITE
                        overwrite output file (default 'update')
  --replace             move infile to a backup copy (appending '~')
  -s, --strip           "export" by stripping documentation or code
  -d, --diff            test for differences to existing file
  --doctest             run doctest.testfile() on the text version
  -e, --execute         execute code (Python only)


Filename Extensions
~~~~~~~~~~~~~~~~~~~

By default ``.txt`` will be appended for literate code and stripped by the
conversion to executable code. I.e. for a Python module `foo`:

* the code source is called ``foo.py``
* the text source is called ``foo.py.txt``
* the HTML rendering is called ``foo.py.html``

.. See also ``filename-extensions.txt``.

Programmatic use
----------------

If pylit.py is in the Python Module Path, it can be imported and used from
other Python programs. The simplest example is the executable wrapper script
pylit that can also be used for customisation_:

.. include:: download/pylit
   :literal:

For more details see e.g. the `helper functions`_ in the `literate source`_.

.. _helper functions: examples/pylit.py.html#helper-functions
.. _literate source: examples/pylit.py.html
.. _pylit: download/pylit

Customisation
-------------

Customisation is possible by overwriting `default values`_  in a wrapper
script like pylit_, e.g. ::

  #!/usr/bin/env python

  import pylit

  pylit.defaults.code_block_marker = '.. code-block:: python'
  pylit.defaults.comment_string = "## "
  pylit.defaults.codeindent = 4
  defaults.text_extensions = [".rst"]

  pylit.main()

To overwrite the "intelligent guesses" by PylitOptions_ and command line
options, pass the option as argument to `pylit.main()`_, e.g.::

  #!/usr/bin/env python

  import pylit
  pylit.main(comment_string = "## ")


.. _default values: examples/pylit.py.html#defaults
.. _PylitOptions:  examples/pylit.py.html#pylitoptions
.. _pylit.main():  examples/pylit.py.html#main
