Usage

This page is part of lp4all documentation.

Documentation generation

Using Lp4all is fairly simple: 

lp4all.py -d outputdirectory list-of-source-files

will generate in outputdirectory the documentation for your project, where list-of-source-files is the list of all files that are part of your project.

There are other options to lp4all, available through the --help option:

  • -d outdir or --directory outdir: give the directory where to output the resulting HTML. By default, current directory;
  • -t str or --tag str: use another comment wiki marker in comments. By default, it is "w";
  • -p name or --project name: set the name to use at the root of the filepath for each page. By default it is "Project";
  • -c file.css or --css file.css: use specified CSS instead of the default one.

Comment marking

By default, Lp4all doesn't consider all comments to be part of the documentation. One must use a specific tag to mark comments that should be rendered by Lp4all. By default, this tag is the single character w, but it can be replaced by any other character, string using the option -t. It can also be set to nothing.

An example for the C language: 

/*w
 * This function computes the number of chocolate paste pots eaten
 * by a pool of ^^n^^ open-source developers during ^^t^^ days.
 */

An example for the Python language: 

#w This class implements a chocolate paste pots. It allows to keep
# track of the remaining quantity of chocolate paste, to keep
# statistics about chocolate paste consumption, and implements various
# methods to manipulate the chocolate paste pot.

.lp4all files

Files with suffix .lp4all are considered having comments written with the Wiki syntax. They are processed as follow:

  • A file foo.lp4all generates a file foo.html in the same directory;
  • If a file foo already exists, the content of file foo.lp4all is added at the beginning of generated file foo.html (so before the code of file foo). As an example, in Lp4all itself, content of file lp4all.py.lp4all is added at the beginning of HTML file lp4all.py.html generated from source file lp4all.py.

Wiki markup

The Wiki syntax is fairly simple :

  • Title level 1: ====title 1====
  • Title level 2: ===title 2===
  • Title level 3: ==title 3==
  • Strong text: **strong**
  • Emphasize text: //emphasize//
  • Strike-through text: ~~strike-through~~
  • Verbatim text: ^ ^verbatim^ ^ (without spaces between ^)
  • Verbatim block: % %verbatim block% % (without spaces between %)
  • External link with text: [[http://www.gnu.org/licenses/gpl1.txt|A link]]
  • External link: [[http://www.gnu.org/licenses/gpl2.txt]]
  • Cross-reference link with some text: [[#id1|link]]
  • Label: [@id1@]

The usage of all tags should be obvious, except probably cross-reference links. One can put labels anywhere in the source code using the [@labelidentifier@] syntax. Then, anywhere in your project, you can link to this label using [[#labelidentifier|Link]].

Tips and tricks

With Mercurial, you can simply get the list of files of your project using the hg locate command. Using Lp4all is then really simple: 

lp4all.py -d /tmp/output `hg locate`