eazy-documentation

2021-04-11

One-shot solution to the CL documentation generator.

Upstream URL

github.com/guicho271828/eazy-documentation

Author

Masataro Asai

License

LGPL
README

Eazy-Documentation img

  • One-shot solution to the CL library documentation generator.

    • It does not require any custom macro/read-macro for annotating your API. Existing documentation generators supports only a limited number of macros (e.g. defun), or requires a user-defined extensions to the parser that extracts the documentation strings (e.g. see docparser). In contrast, this library runs based on the heuristic decision and ranking.
    • It searches the repository for any potential documentation files and embed them in the output as html. Some library (especially the old ones like CFFI) contains a separate documentation / manual as texinfo documents, but they will be all embedded in the output.
    • It supports any markup format supported by Pandoc and makeinfo.
  • Best documentation gives you the most with the least text.

    • Bloated, redundant entries are harmful. Eazy-Documentation therefore provides a compact documentation by compressing the documentation entries in a run-length encoding manner – similar, partly identical entries are merged together as much as possible.
  • Respect the code structure and ordering.

    • Well-written library has a nice, intuitive code structure. This must be exploited by the documentation generator – inspired by Quickdocs.

Example page containing the documentation of eazy-documentation itself can be found here.

Another example for NUMCL library.

Command line interface can be installed via Roswell: ros install guicho271828/eazy-documentation

Usage: eazy-documentation file-or-system output [OPTIONS]

The output is a single file when the output has a html extension; otherwise it will be considered as a directory name. It comes with a CSS and an empty javascript file.

Options are specified as follows:

Options:

keyworddescription
:titleDocumentation title
:headerThe header inserted after the title
:footerThe footer inserted at the bottom
:markupMarkup langage used in the docstring, should be supported by pandoc.
:whitelistWhitelist of the package designators for the symbols being documented
:blacklistBlacklist of the package designators for the symbols being documented
:external-onlyGenerate entries for external symbols only
:tocGenerate a table of contents (toc)
:max-depthThe maximum depth of a toc
:template-classCOMMON-HTML template class, no need to be changed.
:css-listList of CSS scripts to be added to the template.
:js-listList of Javascripts to be added to the template.
:font-listList of Google fonts to be added to the template.
:cleanOverwrite CSS/JS in the target directory
:remote-rootUsed to generate a weblink. Example: https://github.com/<name>/<proj>
:local-rootUsed to generate a weblink. Example: /home/<user>/lisp/<proj>/blob/master
:relativeWhen non-nil, the output is relative to the value of local-root.
:static-filesList of static README files etc.

Requirements

texinfo and up-to-date pandoc (note: some package managers, e.g., Ubuntu's APT, provides a severely outdated version and results in a terrible output. Install the latest version from https://pandoc.org/installing.html )

Author, License, Copyright

Masataro Asai (guicho2.71828@gmail.com)

Licensed under LGPL v3.

Copyright (c) 2019 IBM Corporation

Dependencies (7)

  • alexandria
  • cl-ppcre
  • cl-who
  • common-doc
  • common-html
  • iterate
  • trivia

Dependents (0)

    • GitHub
    • Quicklisp