PAX Manual

1 Introduction
2 Emacs Setup
3 Links and Systems
- 3.1 The mgl-pax ASDF System
- 3.2 The mgl-pax/full ASDF System
4 Background
5 Basics
- 5.1 Parsing
6 PAX Locatives
7 Navigating Sources in Emacs
- 7.1 The mgl-pax/navigate ASDF System
8 Generating Documentation
9 Transcripts
10 Writing Extensions

[in package MGL-PAX with nicknames PAX]

1 Introduction

What if documentation really lived in the code?

Docstrings are already there. If some narrative glued them together, we'd be able develop and explore the code along with the documentation due to their physical proximity. The main tool that PAX provides for this is defsection:

(defsection @foo-random-manual (:title "Foo Random manual")
  "Foo Random is a random number generator library."
  (foo-random-state class)
  (uniform-random function)
  (@foo-random-examples section))

Like this one, sections can have docstrings and references to definitions (e.g. (uniform-random function)). These docstrings and references are the glue. To support interactive development, PAX

makes SLIME's m-. work with references and
adds a documentation browser.

See Emacs Setup.

Beyond interactive workflows, Generating Documentation from sections and all the referenced items in Markdown or HTML format is also implemented.

With the simplistic tools provided, one may emphasize the narrative as with Literate Programming, but documentation is generated from code, not vice versa, and there is no support for chunking.

Code is first, code must look pretty, documentation is code.

Docstrings

PAX automatically recognizes and marks up code with backticks and links code to their definitions. Take, for instance, SBCL's abort function, whose docstring is written in the usual style, uppercasing names of symbols:

(docstring #'abort)
=> "Transfer control to a restart named ABORT, signalling a CONTROL-ERROR if
   none exists."

Note how in the generated documentation, abort is set with a monospace font, while control-error is autolinked:

[function] ABORT &OPTIONAL CONDITION

Transfer control to a restart named abort, signalling a control-error if none exists.

In the following transcript, the above output is rendered from the raw markdown:

(document #'abort :format :markdown)
.. - [function] **ABORT** *&OPTIONAL CONDITION*
..
..     Transfer control to a restart named `ABORT`, signalling a [`CONTROL-ERROR`][7c2c] if
..     none exists.
..
..   [7c2c]: http://www.lispworks.com/documentation/HyperSpec/Body/e_contro.htm "CONTROL-ERROR (MGL-PAX:CLHS CONDITION)"
..

A Complete Example

Here is an example of how it all works together:

(mgl-pax:define-package :foo-random
  (:documentation "This package provides various utilities for random.
  See FOO-RANDOM:@FOO-RANDOM-MANUAL.")
  (:use #:common-lisp #:mgl-pax))

(in-package :foo-random)

(defsection @foo-random-manual (:title "Foo Random manual")
  "FOO-RANDOM is a random number generator library inspired by CL:RANDOM.
  Functions such as UNIFORM-RANDOM use *FOO-STATE* and have a
  :RANDOM-STATE keyword arg."
  (foo-random-state class)
  (state (reader foo-random-state))
  "Hey we can also print states!"
  (print-object (method () (foo-random-state t)))
  (*foo-state* variable)
  (gaussian-random function)
  (uniform-random function)
  ;; This is a subsection.
  (@foo-random-examples section))

(defclass foo-random-state ()
  ((state :reader state)))

(defmethod print-object ((object foo-random-state) stream)
  (print-unreadable-object (object stream :type t)))

(defvar *foo-state* (make-instance 'foo-random-state)
  "Much like *RANDOM-STATE* but uses the FOO algorithm.")

(defun uniform-random (limit &key (random-state *foo-state*))
  "Return a random number from the between 0 and LIMIT (exclusive)
  uniform distribution."
  nil)

(defun gaussian-random (stddev &key (random-state *foo-state*))
  "Return a random number from a zero mean normal distribution with
  STDDEV."
  nil)

(defsection @foo-random-examples (:title "Examples")
  "Let's see the transcript of a real session of someone working
  with FOO:

  ```cl-transcript
  (values (princ :hello) (list 1 2))
  .. HELLO
  => :HELLO
  => (1 2)

  (make-instance 'foo-random-state)
  ==> #<FOO-RANDOM-STATE >
  ```")

Note how (variable *foo-state*) in the defsection form both exports *foo-state* and includes its documentation in @foo-random-manual. The symbols variable and function are just two instances of locatives, which are used in defsection to refer to definitions tied to symbols.

(document @foo-random-manual) generates fancy markdown or HTML output with automatic markup and autolinks uppercase words found in docstrings, numbers sections, and creates a table of contents.

One can even generate documentation for different but related libraries at the same time with the output going to different files but with cross-page links being automatically added for symbols mentioned in docstrings. In fact, this is what PAX World does. See Generating Documentation for some convenience functions to cover the most common cases.

The transcript in the code block tagged with cl-transcript is automatically checked for up-to-dateness when documentation is generated.

Table of Contents

[in package MGL-PAX with nicknames PAX]

Docstrings

A Complete Example