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 or standard out.
Find more details in the tutorial.
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.
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:
#!/usr/bin/env python3
# Load the pylit module::
import pylit
# Configure default settings, e.g. ::
## pylit.defaults.code_block_marker['c++'] = '.. code-block:: c++'
# call the text <--> code converter::
pylit.main()
For more details see e.g. the helper functions in the literate source.
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 = "## ")