==== Usage ==== This page is part of **[[index.html|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, [[lp4all.py.lp4all.html|content of file ^^lp4all.py.lp4all^^]] is added at the beginning of [[lp4all.py.html|HTML file ^^lp4all.py.html^^]] generated from source file ^^lp4all.py^^. === Wiki markup === The Wiki syntax is fairly simple [@firstPage@]: - 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` %%