/docs-builder

A generic documentation builder for Common Lisp projects.

Primary LanguageCommon LispThe UnlicenseUnlicense

Common Lisp Docs Builder

DOCS-BUILDER ASDF System Details

This system is a generic documentation builder for Common Lisp Systems. It able to generate HTML documentation for specified ASDF system.

The idea is to use docs-builder as an universal HTML documentation builders which can be used in a continuous integration pipeline. For example, it is used inside build-docs GitHub action, which can be used to build docs update gh-pages for any Common Lisp library (if it is uses documentation generator supported by docs-builder).

Currently Docs Builder supports only 40ants-doc, MGL-PAX and Geneva, but it can be extended to support other documentation builders, covered by examples in here: cl-doc-systems.github.io.

Usage

Documentation can be built in a few ways: from the lisp REPL, command-line and using the GitHub action.

REPL

From the REPL, you need first to call a docs-builder:build function:

function docs-builder:build system &rest rest &key (error-on-warnings t) &allow-other-keys

Builds HTML documentation for ASDF system and returns absolute path to the dir with docs.

Inside, it will try to guess which documentation builder should be used:

generic-function docs-builder/guesser:guess-builder system

Returns a builder object which can be passed to the docs-builder/builder:build generic-function along with system.

The builder type is guessed using different euristics which depends on a documentation system.

If you want to add support for a new documentation generator, use defguesser macro.

Then it will pass the builder object and ASDF system to the docs-builder/builder:build generic-function:

generic-function docs-builder/builder:build builder system &key local root-sections &allow-other-keys

Builds HTML documentation for ASDF system and returns absolute path to the dir with docs.

Here is an example how to build documentation for :docs-builder ASDF system:

CL-USER> (docs-builder:build :docs-builder)
 <INFO> [02:12:00] docs-builder/core core.lisp (build :before system) -
  Building docs for system #<PACKAGE-INFERRED-SYSTEM "docs-builder"> found at /Users/art/projects/docs-builder/
 <INFO> [02:12:00] docs-builder/builders/mgl-pax/builder builder.lisp (build builder system) -
  Building docs in "/Users/art/projects/docs-builder/docs/build/" dir
#P"/Users/art/projects/docs-builder/docs/build/"

Command-line

You can use builder from command-line. To do this, first install it using Roswell:

# Note, we need to install this patched mgl-pax
# first, to be able to load docs-builder.
# This step in necessary until this pull
# will be merged:
# https://github.com/melisgl/mgl-pax/pull/8

$ ros install 40ants/doc

$ ros install 40ants/docs-builder

Here we call it to build documentation for "docs-builder" ASDF system:

$ build-docs docs-builder
 <INFO> [02:26:32] docs-builder/main main.lisp (main) -
  Quickloading system "docs-builder"
 <INFO> [02:26:34] docs-builder/core core.lisp (build :before system) -
  Building docs for system #<PACKAGE-INFERRED-SYSTEM "docs-builder"> found at /Users/art/projects/docs-builder/
 <INFO> [02:26:34] docs-builder/builders/mgl-pax/builder builder.lisp (build builder system) -
  Building docs in "/Users/art/projects/docs-builder/docs/build/" dir
Scan was called 2146 times.

GitHub Action

If you host your project on the GitHub, then the most easy way to build and host documentation would be to use Github Pages.

To build docs and update the site, create a file .github/workflows/docs.yml with a content like this:

name: 'Docs'

on:
  # This will run tests on pushes
  # to master branch and every monday:
  push:
    branches:
      - 'main'
      - 'master'
  schedule:
    - cron:  '0 10 * * 1'

jobs:
  build-docs:
    runs-on: ubuntu-latest
    
    env:
      LISP: sbcl-bin

    steps:
      - uses: actions/checkout@v1
      - uses: 40ants/setup-lisp@v1
      - uses: 40ants/build-docs@v1
        with:
          asdf-system: cl-info

You'll find more info in the action's documentation.

Additional Params

You can customize a builder by defining a method for this generic function:

generic-function docs-config:docs-config asdf-system

Should return a plist which will be passed as keyword arguments to the documentation builder when building docs for a given asdf-system.

Implement a method, EQL specialized on a concrete ASDF system.

Here is a typical method I use for my own libraries to set a custom theme for 40ants-doc system:

(defmethod docs-config ((system (eql (asdf:registered-system "cl-info"))))
  ;; 40ANTS-DOC-THEME-40ANTS system will bring
  ;; as dependency a full 40ANTS-DOC but we don't want
  ;; unnecessary dependencies here:
  (uiop:symbol-call :ql :quickload :40ants-doc-theme-40ants)
  (list :theme
        (find-symbol "40ANTS-THEME"
                     (find-package "40ANTS-DOC-THEME-40ANTS"))))

Try to load additional dependencies inside the method. This users of your library will not download dependencies needed only for building documentation.

For some special cases it might be useful to return a special key DYNAMIC-BINDINGS. This could be useful, for configuring some custom extensions like it did with interactive demos for the Weblocks. Here is how a method looks like when I configure Weblocks documentation builder:

(defmethod docs-config ((system (eql (asdf:registered-system "weblocks"))))
  ;; ...
  (list :theme
        (find-symbol "40ANTS-THEME"
                     (find-package "40ANTS-DOC-THEME-40ANTS"))
        :dynamic-bindings (list (cons 'weblocks/doc/example:*server-url*
                                      ;; When local examples server is running,
                                      ;; we'll be using it instead of production:
                                      (unless weblocks/doc/example::*port*
                                        "http://examples.40ants.com/"))))

Roadmap

  • Use eazy-documentation as default fallback when no other builder was guessed.
  • Support other documentation generators, collected at https://cl-doc-systems.github.io/
  • Add ability to put a configuration file into the reporitory, for fine-tunning the builder.
[generated by 40ANTS-DOC]