Example of MGL-PAX Common Lisp Documentation Builder

Table of Contents

• 1 Pros & Cons of PAX
  • 1.1 Pros
  • 1.2 Cons
• 2 How to build the documentation
• 3 Handwritten Documentation
• 4 Autogenerated API Reference
• 5 Packages
  • 5.1 EXAMPLE/APP Package
  • 5.2 EXAMPLE/UTILS Package

[in package EXAMPLE-DOCS/DOCS with nicknames EXAMPLE-DOCS]

This is 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 MGL-PAX documentation builder.

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/mgl-pax/

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

Let's review features, provided by MGL-PAX.

1 Pros & Cons of PAX

1.1 Pros

• Markdown is widely used markup format and PAX uses it everywhere.

• Cross-referencing works like a charm and you can reference different types of objects using Locatives.

• New types of documentation objects can be defined in Common Lisp using CLOS. Here is an example.

• Emacs/SLIME integration and ability to jump to a xref objects using M-.

• Ability to generate Markdown README files as well as HTML.

• It is possible to link documentation and sources on the GitHub.

• Docstrings deindentation allows to format code nicely.

• You can generation docs for a multiple ASDF systems with cross-referencing.

• Autoexports all documented symbols. No need to enumerate them in defpackage form.

• There is a nice default HTML theme.

1.2 Cons

• Markdown format may be somewhat limited and probably it can be non-trivial or not possible to extend it in some rare cases.

• The recommended way to mix documentation section with code leads to the runtime dependency from PAX and all it's dependencies. But you might define documentation as a separate ASDF system.

• PAX does not notifies you if some references are missing or there are unused sections. These mistakes can be catched automatically.

• It is inconvenient to write Markdown in docstrings. Is there any way to teach Emacs to use markdown minor mode for documentation strings?

• There is no magic autogenerated reference API. See Autogenerated API Reference.

  But if you prefer another way, it should be easy to write a function which will collect external symbols and generate a MGL-PAX:SECTION object for them.

2 How to build the documentation

MGL-PAX has a number of ways for generation of the docs. But most probably, you'll need only toplevel helpers described in it's section Generating Documentation.

These helpers is able to generate README and HTML docs for an ASDF system.

This example defines it's own wrapper EXAMPLE-DOCS:BUILD-DOCS:

• [function] BUILD-DOCS

It is as simple, as:

(defun build-docs ()
  (mgl-pax:update-asdf-system-readmes @index :example)
  
  (mgl-pax:update-asdf-system-html-docs @index :example
                                        :target-dir "docs/build/"))

This function is used by docs/scripts/build.ros file to generate documentation from GitHub Actions. Or can be called from the REPL.

3 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 the FOO function, I can reference it like this [example/app:foo][function] and it will appear in the code as the link example/app:foo. In most cases you can omit square brakets and just capitalize symbol name.

Comparing MGL-PAX to Coo (here is it's example project, I'd prefer the PAX, because it's ability to mix handwriten sections with documentation extracted from docstrings.

4 Autogenerated API Reference

There is no magic autogenerated reference API. Idea of PAX is that you write docs manually and reference documented symbols. They are automatically exported and this way you library's external API should be documented.

But if you prefer another way, it should be easy to write a function which will collect external symbols and generate a MGL-PAX:SECTION object for them.

5 Packages

5.1 EXAMPLE/APP Package

[in package EXAMPLE/APP]

This is a test package of our example.

It contains only one function definition:

• [function] FOO FIRST &KEY (OTHER 100500)

  This is example function.

  Internally it calls example/utils:do-the-job to do the real job.

  Note, that the link above is broken, but Coo does not warn us when building the docs. Sphinx issues a warning in such case.

What is interesting is that we can continue writing code for the section. Interleaving blocks of text with references to the different Lisp entities.

At some moment we can reference objects from other packages. But to make them cross-referenced, we have to mention them in some section. For example, here FOO references EXAMPLE/UTILS:DO-THE-JOB, which is desribed in the EXAMPLE/UTILS Package.

5.2 EXAMPLE/UTILS Package

[in package EXAMPLE/UTILS]

• [function] DO-THE-JOB FIRST SECOND

  The function does the job.

  It concatenates first and second arguments calling internal function concat.

  On this multiline we'll check how does documentation system processes docstrings.

  By the way, pay attention at the second paragraph where I've used Markdown format to make the word "concatenates" bold.

  Also, we can reference some parts of the documentation. Read more about cross referencing in the Handwritten Documentation chapter.

---

[generated by MGL-PAX]