icon;
icon;
icon;
icon;
icon;
icon;
icon;
icon.
Argot 1.1 |
The OCaml1distribution contains a tool named ocamldoc whose duty is to produce api documentation by extracting information from source comments. Argot is an enhanced html generator for ocamldoc providing additional text formatting, additional tags, and support for symbol search. The name “Argot” stems from the following acronym: Argot is a Raised Generator for the Ocamldoc Tool.
Argot is distributed under the terms of the gpl version 3. This licensing scheme should not cause any problem, as documentation generation will not contaminate code. Moreover, generated documentation files can be used without any restriction.
In order to improve the project, I am primarily looking for testers and bug reporters. Pointing errors in documentation and indicating where it should be enhanced is also very helpful.
Bugs and feature requests can be made at http://bugs.x9c.fr.
Other requetes can be sent to argot@x9c.fr.
Before starting to build Argot, one first have to check that dependencies are already installed. The following elements are needed in order to build Argot:
The configuration of Argot is done by executing sh configure. One can specify elements if they are not correctly inferred by the configure script; the following switches are available:
The actual build of Argot is launched by executing make all. When build is finished, it is possible to run some simple tests by running make tests.
Argot is installed by executing make install. According to local settings, it may be necessary to acquire privileged accesses, running for example sudo make install. The actual installation directory depends on the use of ocamlfind: if present the files are placed inside the Findlib hierarchy, otherwise they are placed in the directory printed by the ocamldoc -customdir command (i. e. $PREFIX/lib/ocaml/ocamldoc/custom).
Once built and installed, using Argot is as simple as switching from:
to:
Argot execution is akin to the previous section, except that the use of findlib implies to pass the installation directory to the ocamldoc tool, thus leading to:
where argot-path is ‘ocamlfind query argot‘.
Generating documentation through ocamlbuild implies to first create a modules.odocl file containing the list of modules (one per line) to generate documentation for. Then, documentation can be generated by executing ocamlbuild modules.docdir/index.html. In order to make use of Argot, the following line should be added to the _tags file:
which marks the index file with the argot tag.
It is thus necessary to handle the aforementioned tag by defining an ocamlbuild plugin. This implies to create a myocamlbuild.ml file with the contents presented by code sample 3.1.
The main code of the plugin calls the define_argot to replace the default html generator with Argot. The define_argot function takes four parameters:
All these parameters correspond to command-line switches whose meaning are detailed in chapter 4 and 6.
open Ocamlbuild_plugin
open Ocamlbuild_pack
let define_argot ?(search=true) ?(frame=true) ?(fulltext=true) defs =
let rec is_native spec = (* heuristics *)
match spec with
| S (hd :: _) -> is_native hd
| A x | P x | Px x | Sh x -> Filename.check_suffix x ".opt"
| V "OCAMLDOC" ->
(try ignore (Command.search_in_path "ocamldoc.opt"); true with _ -> false)
| Quote x -> is_native x
| _ -> true in
let gen =
if is_native !Options.ocamldoc then
[A"-g"; A"argot.cmxs"]
else
[A"-g"; A"argot.cmo"] in
let switches =
if search then
[A"-search"]
@ (if frame then [A"-search-frame"] else [])
@ (if fulltext then [A"-full-text"] else [])
else
[] in
let defs =
List.map
(fun (k, v) -> [(A"-define"); (A k); (A v)])
defs in
let defs = List.flatten defs in
flag ["argot"] (S (gen @ switches @ defs));
let myocamldoc tags =
Ocaml_tools.ocamldoc_l_dir (tags -- "extension:html") in
rule "ocamldoc: argot"
~prod:"%.docdir/index.html"
~dep:"%.odocl"
~stamp:"%.docdir/html.stamp"
~insert:`top
(Ocaml_tools.document_ocaml_project ~ocamldoc:myocamldoc
"%.odocl"
"%.docdir/index.html"
"%.docdir")
let () =
dispatch begin function
| After_rules ->
define_argot ["a", "b"]
| _ -> ()
end
In addition to the already available {b ...} (for bold), {i ...} (for italic), and {e ...} (for emphasized), Argot provides the following text formatting modifiers:
In order to define tables, the following elements can be used:
Code sample 4.1 give an example of a complete table definition.
{table {caption the caption}
{row {header key} {header value}}
{row {data key1} {data {i data1}}}
{row {data key2} {data {i data2}}}
{row {span 2 summary}}}
Token substitution allows one to use the value of either an environment variable or a command-line switch into an html page. This may for example be useful to insert the current date, or to specify the path of an element at documentation generation time:
{token DATE}
file {token FILE_PATH}/file.ext
The value of a token is first searched in -define id value switches passed to the ocamldoc tool, and then searched among the environment variables.
Instead of passing multiple -define switches, it is also possible to load a bunch of definitions from a file through the -definitions file switch. Each line should have the following form: id=value, where the # character introduces comments (ending with the end of the line). Lines that do not conform to the given format are ignored.
Finally, it is possible to refer to other variables when defining a new one (as long as this does not create a circular definition). As an example, the file represented by code sample 4.2 could be passed to the -definitions switch.
BASE=/path/to # prefix NAME=file FILE=$(BASE)/$(NAME).txt
It is possible to include images into the generated pages through {image path}. The image data will be directly embedded into the page using base64 format, in such a way that no external link remains in the generated html. There is thus no need to package the image along with the html pages.
To avoid to use the full path to the image, it is possible to use the aforementioned token substitution inside the image formatter:
{image {token IMAGE_PATH}/img.png}
Then, one has to specify the value for IMAGE_PATH on the command-line through the -define switch seen above:
ocamldoc -define IMAGE_PATH /path/to/images ...
When some explanation, albeit useful, is long and/or may appear as a digression, it is possible to fold it. It means that the texte inside a {fold digression} will appear as an ellipsis (i.e. ...) and will be unfolded (that is revealed) when the ellipsis will be clicked. At the opposite, clicking on the ellipsis while the foldable text is visible will make it disappear. Any formatting instruction can be used in the digression.
Argot also defines a bunch of new tags that can be used to enhance documentation. Some of these tags come with image icons; these have been designed by Mark James, released under the Creative Commons Attribution 2.5 License, and are available at http://www.famfamfam.com/lab/icons/silk/.
The additional tags are:
icon;
icon;
icon;
icon;
icon;
icon;
icon;
icon.
The @license tag will only print its argument if it does not recognize the license, but will create a link to the actual webpage of the license otherwise. The list of predefined licenses is the following (the recognition being case insensitive):
Argot is able to embed search facilities1 into the generated pages when passed the -search command-line switch. The default behaviour is to open a search window by clicking on the magnifying glass (i.e. ) that appears on the index.html page as well as on each module page. However, it is possible to have the search pane in a frame by passing the -search-frame command-line switch; argot_index.html is then the main file.
The search panel is composed of two parts: the upper part allowing to select search criteria, and the lower part displaying results. Clicking on a search result will make the main window point to the clicked element.
Five search modes are provided:
can be made on simple names as well as on fully qualified names. Moreover, all names can be used : values, types, modules, constructors, etc.
is akin to search by name except that all names matching the passed regular expression are returned. The regular expression should be written using the JavaScript syntax2. As an example, it is possible to retrieve all the elements starting with fold by using the following regular expression: fold.*.
allows to search for a value by giving its type3. It is based on the ideas put forward by Roberto Di Cosmo (in particular the ocamlsearch tool for CamlLight). This means that the search does not retrieve values with exactly the same type, but with values whose types are isomorphic4. Practically this means that for example:
note 1: labels are just ignored during search
note 2: a signature containing optional arguments is considered as the set of all signatures that can be generated by including/discarding the optional arugments
is similar to bare search by type, except that types are replaced by their manifests if provided. More, in this context, record types are mapped to tuples by droping the field names. Practically, this means that searching for type float * float -> float will return (among others) Complex.norm whose type is Complex.t -> float. Indeed, as Complex.t has manifest { re : float; im : float; }, it is clearly isomorphic to float * float.
is the ability to search words appearing in the documentation. Words should be separated by spaces, and the result set will present the elements whose documentation contains all the words.
This document was translated from LATEX by HEVEA.