eazy-documentation

This is an example project of Eazy Documentation Common Lisp documentation system.

This repository is part of the https://github.com/cl-doc-systems organization, created to compare different Common Lisp documentation systems

The goal is make it easier for CL software developers to choose proper documentation system and to improve docs in their software!

Resulting documentation can be viewed here:

https://cl-doc-systems.github.io/eazy-documentation/

OSX Installation

brew install pandoc
brew install texinfo
export PATH="/usr/local/opt/texinfo/bin:$PATH"

;; Without this, eazy documentation will not find
;; ASDF system in the local directory:
export CL_SOURCE_REGISTRY=`pwd`/

ros install guicho271828/eazy-documentation

# Eazy Documentation is able to process
# package inferred systems only on ASDF >= 3.3.4
# That is why we need to upgrade it.
ros install asdf

Ubuntu Installation

For ubuntu, replace brew commands with:

sudo apt-get install pandoc texi2html

Example of Eazy Documentation for a Common Lisp library

This is a small library includes a few functions with docstrings and a documentation for the system and all included packages.

The purpose is to demonstrate core features of the eazy-documentation library.

The repository can be used as a template for new libraries if you've choosen Eazy Documentation for documenting your library.

Let's review features, provided by Eazy Documentation.

Pros & Cons of Coo

Pros

• Eazy documentation supports many markups out of the box:
  • docx
  • epub
  • man
  • markdown
  • md
  • mediawiki
  • odt
  • opml
  • org
  • rst
  • tex
  • texi
  • texinfo
  • text
  • textile
  • txt
  • wiki
• By default, Markdown is used for docstrings.
• And the system is able to do proper deindentation for docstrings.
• It automatically discovers README and files in doc folder.
• All lisp files are processed as documents and presented in the resulting HTML file as sections.
• It is able to process docstrins in forms other than standard functions, macros, classes, etc.
• Eazy documentation uses CommonDoc for internal document representation and theoretically you can write your own post-processing.
• There is default color-theme.
• Eazy documentation generates links to the source of every section. This way typos or small errors can be easily fixed on the GitHub. I really like this feature!
• It generates a single HTML file which can be easily searched through in the browser.
• Eazy documentation includes a command line utility and which be called to build documentation for any CL system loadable via ASDF.
• It can be used to build documentation for non Lisp projects. Just point it to any directory with documentation files. For example, take a look at [this manual](manuals.html). However, this feature is only available in my fork and not merged to upstream yet.

Cons

• There is only one way to control the order of files in the doc - to add a numberic prefix.
• There is no cross-referencing is semi-automatic - you have to write links manually.
• And there is not autocheck if all links are correct.
• You have to install pandoc and texinfo into the system :(
• It will be hard to add additional markup to rst or markdown, because they are processed by pandoc.
• I don't like default color theme, but you can redefine it.
• Also I don't like how the document is rendered. Side-bar with files is OK, but different sizes of HTML headers in the main site's section looks ugly. Probably it is possible to use some header level normalization.
• Seems package-inferred systems style is not supported fully, because I don't see EXAMPLE/APP and EXAMPLE/UTILS packages description in this document.
• It generates a single HTML file which can be pretty large if your system is big.

Handwritten documentation

I think the ability to write a large pieces of documentation which aren't bound to a function, class or module is an important feature. This way you can tell the user about some toplevel abstractions and give a bird eye view on the library or system.

For example, handwritten parts of the documentation can provide some code snippets to demonstrate the ways, how to use the library:

(loop repeat 42
      collect (foo "bar" 100500))

And when you are talking about some function or class, you can reference it. For example, if I'm talking about foo function.

Eazy documentation does not provides an eazy way to refer symbols. It would be nice to have EXAMPLE/APP:FOO autolinked, but this does not work.

But the system generates HTML ids for symbols and you can refer them manually. The syntax will be different depending on file's markup language. In reStructured text we can reference FOO like this `FOO <#EXAMPLE/APP:FOO>`_ and it will appear in the code as the link FOO.

Autogenerated API

As I said previously, Eazy Documentation processes Lisp files as a documents and all of them will be presented in the document as sections.

It has unique docstring extration algorithm, which is able to extract docstrings from forms which are not standard.

I've created an example for you:

(defmacro defrule (name &body body)
  "This is a fake macro just to demonstrate how eazy-documentation
   will extract docstrings from it's forms."
  `(defparameter ,name '(,@(rest body))))


(defrule number-one
    "This is a rule's docstring. Nothing special, just a text.

After macro-expansion it will be just:

   (defparameter number-one '((a b c)))

"
  (a b c))

Here is the resulting part of the documentation. Pay attention, there two blocks named defrule:number-one and defparameter:number-one, but both having the same HTML id EXAMPLE/APP:NUMBER-ONE. Because of this, you'll not be able to refer the defrule or the parameter separately. I like the concept of locatives from MGL-PAX, reviewed recently. They allow to select a type of an object you are referring to.