READMEmd[source]

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:

keyword description
:title Documentation title
:header The header inserted after the title
:footer The footer inserted at the bottom
:markup Markup langage used in the docstring, should be supported by pandoc.
:whitelist Whitelist of the package designators for the symbols being documented
:blacklist Blacklist of the package designators for the symbols being documented
:external-only Generate entries for external symbols only
:toc Generate a table of contents (toc)
:max-depth The maximum depth of a toc
:template-class COMMON-HTML template class, no need to be changed.
:css-list List of CSS scripts to be added to the template.
:js-list List of Javascripts to be added to the template.
:font-list List of Google fonts to be added to the template.
:clean Overwrite CSS/JS in the target directory
:remote-root Used to generate a weblink. Example: https://github.com/<name>/<proj>
:local-root Used to generate a weblink. Example: /home/<user>/lisp/<proj>/blob/master
:relative When non-nil, the output is relative to the value of local-root.
:static-files List 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 )

Masataro Asai (guicho2.71828@gmail.com)

Licensed under LGPL v3.

Copyright (c) 2019 IBM Corporation

src

0packagelisp[source]

defpackage
eazy-documentation

This package provides an easy way to extract documentations from a lisp source code.

Advantages over the existing libraries:

  • EAZY-DOCUMENTATION can generate documents from a single file or an ASDF system. Run (eazy-documentation:generate-html <file-or-system> "index.html") No additional quirks are necessary.

  • Extraction is heuristic and robust. It is easily automated and can handle unknown user-defined macro whose name begins with DEF.

  • As per Quickdocs, it respects the file and directory structure. Well-written, maintainable libraries have a great readability in the source code. This should be respected and the documentation generator should respect this structure.

  • It minimizes the clutter in the auto-generateded output by detecting and grouping the similar documentation entries. For example, these entries are grouped together:

    • Functions with the same lambda-list and docstrings.
    • Variables with the same docstrings.
    • Any DEF-something macro entries with the same name and missing documentations.
  • Typesetting and syntax highlighting of docstring is done by Pandoc which supports a wide range of language and format support.

    Run curl -sSL https://get.haskellstack.org/ | sh && stack install pandoc to install the latest Pandoc.

  • The output is a common-doc object, thus easily pluggable to the existing emitter for them.

1definitionlisp[source]

defmethod
print-object
(def def) s

(documentation missing)

1raw-htmllisp[source]

define-nodedefclass
raw-text-node
common-html.emitter

defun
convert-file-to-html-string
pin

defun
convert-string-to-html-string
string markup

defun
convert-file-to-ascii-string
pin

defun
convert-string-to-ascii-string
string markup

(all documentation missing)

4userlisp[source]

defun
extract-definitions-from-file
file &key (title (no title) title-supplied-p) (header ) (footer ) (whitelist nil) (blacklist 'nil) (external-only t) (toc t) (max-depth 2) (template-class 'eazy-template) (css-list *default-css*) (js-list *default-js*) (font-list *default-fonts*) (clean nil) ((remote-root *remote-root*) nil) ((local-root *local-root*) nil) (relative nil) (static-files nil) (markup gfm) &allow-other-keys

defun
extract-definitions-from-system
system &key (title (no title) title-supplied-p) (header ) (footer ) (whitelist nil) (blacklist 'nil) (external-only t) (toc t) (max-depth 2) (template-class 'eazy-template) (css-list *default-css*) (js-list *default-js*) (font-list *default-fonts*) (clean nil) ((remote-root *remote-root*) nil) ((local-root *local-root*) nil) (relative nil) (static-files nil) (markup gfm) &allow-other-keys

defun
generate-commondoc-from-file
file &rest args &key (title (no title) title-supplied-p) (header ) (footer ) (whitelist nil) (blacklist 'nil) (external-only t) (toc t) (max-depth 2) (template-class 'eazy-template) (css-list *default-css*) (js-list *default-js*) (font-list *default-fonts*) (clean nil) ((remote-root *remote-root*) nil) ((local-root *local-root*) nil) (relative nil) (static-files nil) (markup gfm) &allow-other-keys

defun
generate-commondoc-from-system
system &rest args &key (title (no title) title-supplied-p) (header ) (footer ) (whitelist nil) (blacklist 'nil) (external-only t) (toc t) (max-depth 2) (template-class 'eazy-template) (css-list *default-css*) (js-list *default-js*) (font-list *default-fonts*) (clean nil) ((remote-root *remote-root*) nil) ((local-root *local-root*) nil) (relative nil) (static-files nil) (markup gfm) &allow-other-keys

defun
generate-html-from-file
file *target-pathname* &rest args &key (title (no title) title-supplied-p) (header ) (footer ) (whitelist nil) (blacklist 'nil) (external-only t) (toc t) (max-depth 2) (template-class 'eazy-template) (css-list *default-css*) (js-list *default-js*) (font-list *default-fonts*) (clean nil) ((remote-root *remote-root*) nil) ((local-root *local-root*) nil) (relative nil) (static-files nil) (markup gfm) &allow-other-keys

defun
generate-html-from-dir
dir *target-pathname* &rest args &key (title (no title) title-supplied-p) (header ) (footer ) (whitelist nil) (blacklist 'nil) (external-only t) (toc t) (max-depth 2) (template-class 'eazy-template) (css-list *default-css*) (js-list *default-js*) (font-list *default-fonts*) (clean nil) ((remote-root *remote-root*) nil) ((local-root *local-root*) nil) (relative nil) (static-files nil) (markup gfm) &allow-other-keys

defun
generate-html-from-system
system *target-pathname* &rest args &key (title (no title) title-supplied-p) (header ) (footer ) (whitelist nil) (blacklist 'nil) (external-only t) (toc t) (max-depth 2) (template-class 'eazy-template) (css-list *default-css*) (js-list *default-js*) (font-list *default-fonts*) (clean nil) ((remote-root *remote-root*) nil) ((local-root *local-root*) nil) (relative nil) (static-files nil) (markup gfm) &allow-other-keys

defun
generate-html
file-or-system *target-pathname* &rest args &key (title (no title) title-supplied-p) (header ) (footer ) (whitelist nil) (blacklist 'nil) (external-only t) (toc t) (max-depth 2) (template-class 'eazy-template) (css-list *default-css*) (js-list *default-js*) (font-list *default-fonts*) (clean nil) ((remote-root *remote-root*) nil) ((local-root *local-root*) nil) (relative nil) (static-files nil) (markup gfm) &allow-other-keys

Options:

keyword description
:title Documentation title
:header The header inserted after the title
:footer The footer inserted at the bottom
:markup Markup langage used in the docstring, should be supported by pandoc.
:whitelist Whitelist of the package designators for the symbols being documented
:blacklist Blacklist of the package designators for the symbols being documented
:external-only Generate entries for external symbols only
:toc Generate a table of contents (toc)
:max-depth The maximum depth of a toc
:template-class COMMON-HTML template class, no need to be chanded.
:css-list List of CSS scripts to be added to the template.
:js-list List of Javascripts to be added to the template.
:font-list List of Google fonts to be added to the template.
:clean Overwrite CSS/JS in the target directory
:remote-root Used to generate a weblink. Example: https://github.com//
:local-root Used to generate a weblink. Example: /home//lisp//blob/master
:relative When non-nil, the output is relative to the value of local-root.
:static-files List of static README files etc.

5templatelisp[source]

defmethod
render
(template eazy-template) (document document) content-string

The simplest template.

defmethod
render-section
(template eazy-template) (document document) (section section) content-string

The simplest section template.

5templatelisp[source]

defun
main
&rest argv

(documentation missing)