- Description: A meta documentation builder for Common Lisp projects.
- Licence: Unlicense
- Author: Alexander Artemenko
- Homepage: https://40ants.com/docs-builder
- Bug tracker: https://github.com/40ants/docs-builder/issues
- Source control: GIT
- Depends on: 40ants-doc, alexandria, docs-config, log4cl, uiop
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.
Documentation can be built in a few ways: from the lisp REPL, command-line and
using the GitHub action.
From the REPL, you need first to call a docs-builder:build function:
functiondocs-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-functiondocs-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-functiondocs-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-builderASDF 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/"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-builderHere 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.
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-latestenv:
LISP: sbcl-binsteps:
- uses: actions/checkout@v1
- uses: 40ants/setup-lisp@v1
- uses: 40ants/build-docs@v1with:
asdf-system: cl-infoYou'll find more info in the action's documentation.
You can customize a builder by defining a method for this generic function:
generic-functiondocs-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:
(defmethoddocs-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/"))))
- 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.