idris-lang/Idris-dev — pull request #1074 by PhilipRasmussen (2014-04-17 02:21:32+00:00)
Title: IdrisDoc

IdrisDoc is documentation tool for Idris producing HTML output.
The output consists of an index page, with a list of documented namespaces, and a documentation page for each included namespace.
Namespaces document the functions, data types (incl. constructors), and type classes (incl. methods) using information from Idris.Docs. Type signatures are annotated with Conor color codes (except variables are black to give room for the other colours), and types and functions are hyperlinks to their documentation entries. For an idea of the layout, see the preview posted on the mailing list -- only few changes has been made since.

There are two ways to use the tool, either directly from the terminal, using 'idris --mkdoc < path/to/package.ipkg >', or from the REPL using ':mkdoc < namespace1 > < namespace2 > ...'.
The command line version will generate documentation for the namespaces corresponding to the modules in an Idris package, while the REPL command will generate documentation for the specified namespace(s).

In addition to documenting the provided namespaces, any namespaces referred from them through type signatures will also be included in the documentation.
The --mkdoc method writes documentation to './< package_name >_doc', while the :mkdoc method writes documentation to './doc'. If the output directory already exists, output will only be generated if the directory contains an 'IdrisDoc' file -- this is a safety mechanism to avoid accidental overwrites of files.
The IdrisDoc file contains information about which namespaces already are documented in this output directory, and it is used to merge the existing documentation with newly generated documentation.
Existing namespace documentation is overwritten if the new documentation generation documents a namespace by the same name. Otherwise no overwrites are done, and an updated index page will list both old and new namespaces.

IdrisDoc is not without some bugs or missing functionality, however:
* Due to missing information from Idris.Docs, typeclass signatures are lacking. Only the name is shown. E.g. 'class Extend a => Name a' will only be shown as 'class Name'.
* Record types are documented with a data type and each accessor function separate. Again, this is because the information not readily was available from Idris.Docs, which document record types this way.
* Idris.Docs does not properly report docstrings for typeclass methods. IdrisDoc therefore does neither.
* Argument names are recognised as bound variables. Though the current styling does not reveal the difference, making variables magenta will also colour the argument labels magenta.
* IdrisDoc currently naively translates the module names of an .ipkg into namespace names. Because correspondance between a file's name and its contained module only is by convention, IdrisDoc is not able to find the namespaces of files which breaks the convention. If IdrisDoc cannot find a namespace, a warning is currently printed.
* IdrisDoc currently does not report the instances of typeclasses. It is a useful feature, but the information was not readily extractable and is therefore not a part of this (initial) version.
* The documentation merge is not perfect. The index file is guaranteed to list all documented namespaces, but a namespace file may be updated with prior declarations removed, and other namespaces may still refer these, now deleted, namespace members.
* By design, only explicit arguments of non-hidden namespace members are showed. For internal usage this default may not be enough.

For this pull request tests have not been written. They will be added in a later pull request.
IdrisDoc is however usable, and have been tested to work and appear similar in the latest versions of Firefox, Safari, Chrome, and Internet Explorer.