The docs-builder Reference Manual

3.1.1 docs-builder/docs-builder.asd

Source

docs-builder.asd.

Parent Component

docs-builder (system).

ASDF Systems

• docs-builder.
• docs-builder/core.
• docs-builder/builder.
• docs-builder/guesser.
• docs-builder/changelog.
• docs-builder/builders/40ants-doc/guesser.
• docs-builder/utils.
• docs-builder/builders/mgl-pax/guesser.
• docs-builder/builders/geneva/guesser.
• docs-builder/docs.

---

3.1.2 docs-config/docs-config.asd

Source

docs-config.asd.

Parent Component

docs-config (system).

ASDF Systems

• docs-config.
• docs-config/config.

---

3.1.3 docs-builder/core/file-type.lisp

Source

docs-builder.asd.

Parent Component

docs-builder/core (system).

Packages

docs-builder.

Public Interface

• build (function).
• documentation-has-problems (condition).
• num-of-warnings (reader method).

---

3.1.4 docs-builder/builder/file-type.lisp

Source

docs-builder.asd.

Parent Component

docs-builder/builder (system).

Packages

docs-builder/builder.

Public Interface

build (generic function).

---

3.1.5 docs-config/config/file-type.lisp

Source

docs-config.asd.

Parent Component

docs-config/config (system).

Packages

docs-config.

Public Interface

docs-config (generic function).

---

3.1.6 docs-builder/guesser/file-type.lisp

Source

docs-builder.asd.

Parent Component

docs-builder/guesser (system).

Packages

docs-builder/guesser.

Public Interface

• defguesser (macro).
• guess-builder (generic function).

Internals

• *guessers* (special variable).
• *system-to-builder* (special variable).
• find-or-load-system (function).

---

3.1.7 docs-builder/changelog/file-type.lisp

Source

docs-builder.asd.

Parent Component

docs-builder/changelog (system).

Packages

docs-builder/changelog.

Public Interface

@changelog (special variable).

Internals

• 0.1.0 (special variable).
• 0.10.0 (special variable).
• 0.11.0 (special variable).
• 0.2.0 (special variable).
• 0.3.0 (special variable).
• 0.4.0 (special variable).
• 0.4.1 (special variable).
• 0.4.2 (special variable).
• 0.5.0 (special variable).
• 0.5.1 (special variable).
• 0.5.2 (special variable).
• 0.5.3 (special variable).
• 0.6.0 (special variable).
• 0.6.1 (special variable).
• 0.6.2 (special variable).
• 0.7.0 (special variable).
• 0.7.1 (special variable).
• 0.8.0 (special variable).
• 0.9.0 (special variable).
• 0.9.1 (special variable).

---

3.1.8 docs-builder/builders/40ants-doc/guesser/file-type.lisp

Source

docs-builder.asd.

Parent Component

docs-builder/builders/40ants-doc/guesser (system).

Packages

docs-builder/builders/40ants-doc/guesser.

Internals

• 40ants-doc (function).
• @index (special variable).
• @todo (special variable).

---

3.1.9 docs-builder/utils/file-type.lisp

Source

docs-builder.asd.

Parent Component

docs-builder/utils (system).

Packages

docs-builder/utils.

Public Interface

• external-dependencies (function).
• system-packages (generic function).

Internals

• @utils (special variable).
• ensure-supported (function).

---

3.1.10 docs-builder/builders/mgl-pax/guesser/file-type.lisp

Source

docs-builder.asd.

Parent Component

docs-builder/builders/mgl-pax/guesser (system).

Packages

docs-builder/builders/mgl-pax/guesser.

Internals

• @index (special variable).
• mgl-pax (function).

---

3.1.11 docs-builder/builders/geneva/guesser/file-type.lisp

Source

docs-builder.asd.

Parent Component

docs-builder/builders/geneva/guesser (system).

Packages

docs-builder/builders/geneva/guesser.

Internals

• @index (special variable).
• @todo (special variable).
• geneva (function).

---

3.1.12 docs-builder/docs/file-type.lisp

Source

docs-builder.asd.

Parent Component

docs-builder/docs (system).

Packages

docs-builder/docs.

Public Interface

• @index (special variable).
• @readme (special variable).
• docs-config (method).

Internals

• *badges* (special variable).
• *ignore-words* (special variable).
• *introduction* (special variable).
• @adding-a-build-method (special variable).
• @adding-a-builder-class (special variable).
• @adding-a-guesser (special variable).
• @additional-params (special variable).
• @api (special variable).
• @command-line-usage (special variable).
• @extending (special variable).
• @github-action-usage (special variable).
• @repl-usage (special variable).
• @roadmap (special variable).
• @supported-builders (special variable).
• @usage (special variable).

---

5.1.1 Special variables

Special Variable: @changelog ¶

Package

docs-builder/changelog.

Source

file-type.lisp.

Special Variable: @index ¶

Package

docs-builder.

Source

file-type.lisp.

Special Variable: @readme ¶

Package

docs-builder.

Source

file-type.lisp.

---

5.1.2 Macros

Macro: defguesser (name (system) &body body) ¶

Package

docs-builder/guesser.

Source

file-type.lisp.

---

5.1.3 Ordinary functions

Function: build (system &rest rest &key error-on-warnings &allow-other-keys) ¶

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

Package

docs-builder.

Source

file-type.lisp.

Function: external-dependencies (system &key all) ¶

Returns a list of string with names of external dependencies of the system.

It works with package-inferred systems too, recursively collecting external-dependencies of all subsystems.

Warning! By default, this function does not return dependencies of dependencies. To get them all, add :ALL T option.

Package

docs-builder/utils.

Source

file-type.lisp.

---

5.1.4 Generic functions

Generic Function: build (builder system &key &allow-other-keys) ¶

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

Package

docs-builder/builder.

Source

file-type.lisp.

Methods

Method: build :around (builder (system system) &rest rest &key &allow-other-keys) ¶

Method: build (builder (system symbol) &rest rest &key &allow-other-keys) ¶

Method: build (builder (system string) &rest rest &key &allow-other-keys) ¶

Generic Function: 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:

“‘lisp
(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](https://40ants.com/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/")))) “‘

Package

docs-config.

Source

file-type.lisp.

Methods

Method: docs-config ((system (eql #<asdf/package-inferred-system:package-inferred-system "docs-builder">))) ¶

Source

file-type.lisp.

Method: docs-config (system) ¶

Method: docs-config ((system-name symbol)) ¶

Method: docs-config ((system-name string)) ¶

Generic Function: 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.

Package

docs-builder/guesser.

Source

file-type.lisp.

Methods

Method: guess-builder ((system system)) ¶

Method: guess-builder ((system string)) ¶

Method: guess-builder ((system symbol)) ¶

Generic Reader: num-of-warnings (condition) ¶

Package

docs-builder.

Methods

Reader Method: num-of-warnings ((condition documentation-has-problems)) ¶

Source

file-type.lisp.

Target Slot

num-of-warnings.

Generic Function: system-packages (system) ¶

Returns a list of packages created by ASDF system.

Default implementation returns a package having the same name as a system and all packages matched to package-inferred subsystems:

“‘
CL-USER> (docs-builder/utils:system-packages :docs-builder) (#<PACKAGE "DOCS-BUILDER">
#<PACKAGE "DOCS-BUILDER/UTILS">
#<PACKAGE "DOCS-BUILDER/GUESSER">
#<PACKAGE "DOCS-BUILDER/BUILDERS/GENEVA/GUESSER">
#<PACKAGE "DOCS-BUILDER/BUILDER">
#<PACKAGE "DOCS-BUILDER/BUILDERS/MGL-PAX/GUESSER">
#<PACKAGE "DOCS-BUILDER/DOCS">
#<PACKAGE "DOCS-BUILDER/BUILDERS/MGL-PAX/BUILDER">)
“‘

This function can be used by builder to find pieces of documentation. For example, DOCS-BUILDER/BUILDERS/MGL-PAX/GUESSER:@INDEX
builder uses it to find documentation sections.

Package

docs-builder/utils.

Source

file-type.lisp.

Methods

Method: system-packages ((system string)) ¶

Method: system-packages ((system symbol)) ¶

Method: system-packages ((system system)) ¶

---

5.1.5 Conditions

Condition: documentation-has-problems ¶

Package

docs-builder.

Source

file-type.lisp.

Direct superclasses

error.

Direct methods

num-of-warnings.

Direct slots

Slot: num-of-warnings ¶

Initargs

:num-of-warnings

Readers

num-of-warnings.

Writers

This slot is read-only.

---

5.2.1 Special variables

Special Variable: *badges* ¶

Package

docs-builder/docs.

Source

file-type.lisp.

Special Variable: *guessers* ¶

Package

docs-builder/guesser.

Source

file-type.lisp.

Special Variable: *ignore-words* ¶

Package

docs-builder/docs.

Source

file-type.lisp.

Special Variable: *introduction* ¶

Package

docs-builder/docs.

Source

file-type.lisp.

Special Variable: *system-to-builder* ¶

Package

docs-builder/guesser.

Source

file-type.lisp.

Special Variable: 0.1.0 ¶

Package

docs-builder/changelog.

Source

file-type.lisp.

Special Variable: 0.10.0 ¶

Package

docs-builder/changelog.

Source

file-type.lisp.

Special Variable: 0.11.0 ¶

Package

docs-builder/changelog.

Source

file-type.lisp.

Special Variable: 0.2.0 ¶

Package

docs-builder/changelog.

Source

file-type.lisp.

Special Variable: 0.3.0 ¶

Package

docs-builder/changelog.

Source

file-type.lisp.

Special Variable: 0.4.0 ¶

Package

docs-builder/changelog.

Source

file-type.lisp.

Special Variable: 0.4.1 ¶

Package

docs-builder/changelog.

Source

file-type.lisp.

Special Variable: 0.4.2 ¶

Package

docs-builder/changelog.

Source

file-type.lisp.

Special Variable: 0.5.0 ¶

Package

docs-builder/changelog.

Source

file-type.lisp.

Special Variable: 0.5.1 ¶

Package

docs-builder/changelog.

Source

file-type.lisp.

Special Variable: 0.5.2 ¶

Package

docs-builder/changelog.

Source

file-type.lisp.

Special Variable: 0.5.3 ¶

Package

docs-builder/changelog.

Source

file-type.lisp.

Special Variable: 0.6.0 ¶

Package

docs-builder/changelog.

Source

file-type.lisp.

Special Variable: 0.6.1 ¶

Package

docs-builder/changelog.

Source

file-type.lisp.

Special Variable: 0.6.2 ¶

Package

docs-builder/changelog.

Source

file-type.lisp.

Special Variable: 0.7.0 ¶

Package

docs-builder/changelog.

Source

file-type.lisp.

Special Variable: 0.7.1 ¶

Package

docs-builder/changelog.

Source

file-type.lisp.

Special Variable: 0.8.0 ¶

Package

docs-builder/changelog.

Source

file-type.lisp.

Special Variable: 0.9.0 ¶

Package

docs-builder/changelog.

Source

file-type.lisp.

Special Variable: 0.9.1 ¶

Package

docs-builder/changelog.

Source

file-type.lisp.

Special Variable: @adding-a-build-method ¶

Package

docs-builder/docs.

Source

file-type.lisp.

Special Variable: @adding-a-builder-class ¶

Package

docs-builder/docs.

Source

file-type.lisp.

Special Variable: @adding-a-guesser ¶

Package

docs-builder/docs.

Source

file-type.lisp.

Special Variable: @additional-params ¶

Package

docs-builder/docs.

Source

file-type.lisp.

Special Variable: @api ¶

Package

docs-builder/docs.

Source

file-type.lisp.

Special Variable: @command-line-usage ¶

Package

docs-builder/docs.

Source

file-type.lisp.

Special Variable: @extending ¶

Package

docs-builder/docs.

Source

file-type.lisp.

Special Variable: @github-action-usage ¶

Package

docs-builder/docs.

Source

file-type.lisp.

Special Variable: @index ¶

Package

docs-builder/builders/mgl-pax/guesser.

Source

file-type.lisp.

Special Variable: @index ¶

Package

docs-builder/builders/geneva/guesser.

Source

file-type.lisp.

Special Variable: @index ¶

Package

docs-builder/builders/40ants-doc/guesser.

Source

file-type.lisp.

Special Variable: @repl-usage ¶

Package

docs-builder/docs.

Source

file-type.lisp.

Special Variable: @roadmap ¶

Package

docs-builder/docs.

Source

file-type.lisp.

Special Variable: @supported-builders ¶

Package

docs-builder/docs.

Source

file-type.lisp.

Special Variable: @todo ¶

Package

docs-builder/builders/geneva/guesser.

Source

file-type.lisp.

Special Variable: @todo ¶

Package

docs-builder/builders/40ants-doc/guesser.

Source

file-type.lisp.

Special Variable: @usage ¶

Package

docs-builder/docs.

Source

file-type.lisp.

Special Variable: @utils ¶

Package

docs-builder/utils.

Source

file-type.lisp.

---

5.2.2 Ordinary functions

Function: 40ants-doc (system) ¶

Package

docs-builder/builders/40ants-doc/guesser.

Source

file-type.lisp.

Function: ensure-supported (item) ¶

Returns either a string or nil if this item should be skipped.

ITEM can be a string or a list like:

(:feature :windows "winhttp")

Package

docs-builder/utils.

Source

file-type.lisp.

Function: find-or-load-system (system-name) ¶

Package

docs-builder/guesser.

Source

file-type.lisp.

Function: geneva (system) ¶

Package

docs-builder/builders/geneva/guesser.

Source

file-type.lisp.

Function: mgl-pax (system) ¶

Package

docs-builder/builders/mgl-pax/guesser.

Source

file-type.lisp.

---