Next: Introduction, Previous: (dir), Up: (dir) [Contents][Index]
This is the docs-builder Reference Manual, generated automatically by Declt version 3.0 "Montgomery Scott" on Sun May 15 04:39:14 2022 GMT+0.
| • Introduction | What docs-builder is all about | |
| • Systems | The systems documentation | |
| • Files | The files documentation | |
| • Packages | The packages documentation | |
| • Definitions | The symbols documentation | |
| • Indexes | Concepts, functions, variables and data types |
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
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:
docs-builder:build system &rest rest &key (error-on-warnings t) &allow-other-keysBuilds 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:
docs-builder/guesser:guess-builder systemReturns 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:
docs-builder/builder:build builder system &key local root-sections &allow-other-keysBuilds 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/"
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.
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.
You can customize a builder by defining a method for this generic function:
docs-config:docs-config asdf-systemShould 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:find-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:find-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.
Next: Files, Previous: Introduction, Up: Top [Contents][Index]
The main system appears first, followed by any subsystem dependency.
Next: The docs-builder/builders/40ants-doc/guesser system, Previous: Systems, Up: Systems [Contents][Index]
Alexander Artemenko
(:git "https://github.com/40ants/docs-builder")
Unlicense
A meta documentation builder for Common Lisp projects.
docs-builder.asd (file)
Next: The docs-builder/docs system, Previous: The docs-builder system, Up: Systems [Contents][Index]
Alexander Artemenko
(:git "https://github.com/40ants/docs-builder")
Unlicense
docs-builder.asd (file)
file-type.lisp (file)
Next: The docs-builder/builders/mgl-pax/guesser system, Previous: The docs-builder/builders/40ants-doc/guesser system, Up: Systems [Contents][Index]
Alexander Artemenko
(:git "https://github.com/40ants/docs-builder")
Unlicense
docs-builder.asd (file)
file-type.lisp (file)
Next: The docs-builder/builders/geneva/guesser system, Previous: The docs-builder/docs system, Up: Systems [Contents][Index]
Alexander Artemenko
(:git "https://github.com/40ants/docs-builder")
Unlicense
docs-builder.asd (file)
file-type.lisp (file)
Next: The docs-builder/utils system, Previous: The docs-builder/builders/mgl-pax/guesser system, Up: Systems [Contents][Index]
Alexander Artemenko
(:git "https://github.com/40ants/docs-builder")
Unlicense
docs-builder.asd (file)
file-type.lisp (file)
Next: The docs-builder/core system, Previous: The docs-builder/builders/geneva/guesser system, Up: Systems [Contents][Index]
Alexander Artemenko
(:git "https://github.com/40ants/docs-builder")
Unlicense
40ants-doc
docs-builder.asd (file)
file-type.lisp (file)
Next: The docs-builder/builder system, Previous: The docs-builder/utils system, Up: Systems [Contents][Index]
Alexander Artemenko
(:git "https://github.com/40ants/docs-builder")
Unlicense
docs-builder.asd (file)
file-type.lisp (file)
Next: The docs-config system, Previous: The docs-builder/core system, Up: Systems [Contents][Index]
Alexander Artemenko
(:git "https://github.com/40ants/docs-builder")
Unlicense
docs-builder.asd (file)
file-type.lisp (file)
Next: The docs-config/config system, Previous: The docs-builder/builder system, Up: Systems [Contents][Index]
Alexander Artemenko
(:git "https://github.com/40ants/docs-builder")
Unlicense
A protocol for defining configuration for DOCS-BUILDER system.
docs-config/config (system)
docs-config.asd (file)
Next: The docs-builder/guesser system, Previous: The docs-config system, Up: Systems [Contents][Index]
Alexander Artemenko
(:git "https://github.com/40ants/docs-builder")
Unlicense
docs-config.asd (file)
file-type.lisp (file)
Next: The docs-builder/changelog system, Previous: The docs-config/config system, Up: Systems [Contents][Index]
Alexander Artemenko
(:git "https://github.com/40ants/docs-builder")
Unlicense
docs-builder.asd (file)
file-type.lisp (file)
Previous: The docs-builder/guesser system, Up: Systems [Contents][Index]
Alexander Artemenko
(:git "https://github.com/40ants/docs-builder")
Unlicense
40ants-doc/changelog
docs-builder.asd (file)
file-type.lisp (file)
Files are sorted by type and then listed depth-first from the systems components trees.
| • Lisp files |
Next: The docs-builder․asd file, Previous: Lisp files, Up: Lisp files [Contents][Index]
/home/quickref/quicklisp/dists/quicklisp/software/docs-builder-20211209-git/docs-config.asd
Next: The docs-builder/builders/40ants-doc/guesser/file-type․lisp file, Previous: The docs-config․asd file, Up: Lisp files [Contents][Index]
/home/quickref/quicklisp/dists/quicklisp/software/docs-builder-20211209-git/docs-builder.asd
Next: The docs-builder/docs/file-type․lisp file, Previous: The docs-builder․asd file, Up: Lisp files [Contents][Index]
builders/40ants-doc/guesser.lisp
Next: The docs-builder/builders/mgl-pax/guesser/file-type․lisp file, Previous: The docs-builder/builders/40ants-doc/guesser/file-type․lisp file, Up: Lisp files [Contents][Index]
docs-builder/docs (system)
docs.lisp
Next: The docs-builder/builders/geneva/guesser/file-type․lisp file, Previous: The docs-builder/docs/file-type․lisp file, Up: Lisp files [Contents][Index]
builders/mgl-pax/guesser.lisp
Next: The docs-builder/utils/file-type․lisp file, Previous: The docs-builder/builders/mgl-pax/guesser/file-type․lisp file, Up: Lisp files [Contents][Index]
docs-builder/builders/geneva/guesser (system)
builders/geneva/guesser.lisp
Next: The docs-builder/core/file-type․lisp file, Previous: The docs-builder/builders/geneva/guesser/file-type․lisp file, Up: Lisp files [Contents][Index]
docs-builder/utils (system)
utils.lisp
Next: The docs-builder/builder/file-type․lisp file, Previous: The docs-builder/utils/file-type․lisp file, Up: Lisp files [Contents][Index]
docs-builder/core (system)
core.lisp
Next: The docs-config/config/file-type․lisp file, Previous: The docs-builder/core/file-type․lisp file, Up: Lisp files [Contents][Index]
docs-builder/builder (system)
builder.lisp
Next: The docs-builder/guesser/file-type․lisp file, Previous: The docs-builder/builder/file-type․lisp file, Up: Lisp files [Contents][Index]
docs-config/config (system)
config.lisp
Next: The docs-builder/changelog/file-type․lisp file, Previous: The docs-config/config/file-type․lisp file, Up: Lisp files [Contents][Index]
docs-builder/guesser (system)
guesser.lisp
Previous: The docs-builder/guesser/file-type․lisp file, Up: Lisp files [Contents][Index]
docs-builder/changelog (system)
changelog.lisp
@changelog (special variable)
Next: Definitions, Previous: Files, Up: Top [Contents][Index]
Packages are listed by definition order.
Next: The docs-builder/docs package, Previous: Packages, Up: Packages [Contents][Index]
file-type.lisp (file)
common-lisp
Next: The docs-builder/builders/mgl-pax/guesser package, Previous: The docs-builder/builders/40ants-doc/guesser package, Up: Packages [Contents][Index]
file-type.lisp (file)
common-lisp
Next: The docs-builder/builders/geneva/guesser package, Previous: The docs-builder/docs package, Up: Packages [Contents][Index]
file-type.lisp (file)
common-lisp
Next: The docs-builder/utils package, Previous: The docs-builder/builders/mgl-pax/guesser package, Up: Packages [Contents][Index]
file-type.lisp (file)
common-lisp
Next: The docs-builder package, Previous: The docs-builder/builders/geneva/guesser package, Up: Packages [Contents][Index]
The utils for documentation builders.
file-type.lisp (file)
common-lisp
Next: The docs-builder/builder package, Previous: The docs-builder/utils package, Up: Packages [Contents][Index]
file-type.lisp (file)
docs-builder/core
common-lisp
Next: The docs-config package, Previous: The docs-builder package, Up: Packages [Contents][Index]
file-type.lisp (file)
common-lisp
Next: The docs-builder/guesser package, Previous: The docs-builder/builder package, Up: Packages [Contents][Index]
file-type.lisp (file)
docs-config/config
common-lisp
Next: The docs-builder/changelog package, Previous: The docs-config package, Up: Packages [Contents][Index]
file-type.lisp (file)
common-lisp
Previous: The docs-builder/guesser package, Up: Packages [Contents][Index]
file-type.lisp (file)
common-lisp
@changelog (special variable)
Definitions are sorted by export status, category, package, and then by lexicographic order.
| • Exported definitions | ||
| • Internal definitions |
Next: Internal definitions, Previous: Definitions, Up: Definitions [Contents][Index]
| • Exported special variables | ||
| • Exported macros | ||
| • Exported functions | ||
| • Exported generic functions | ||
| • Exported conditions |
Next: Exported macros, Previous: Exported definitions, Up: Exported definitions [Contents][Index]
file-type.lisp (file)
file-type.lisp (file)
file-type.lisp (file)
Next: Exported functions, Previous: Exported special variables, Up: Exported definitions [Contents][Index]
file-type.lisp (file)
Next: Exported generic functions, Previous: Exported macros, Up: Exported definitions [Contents][Index]
Builds HTML documentation for ASDF system and returns absolute path to the dir with docs.
file-type.lisp (file)
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.
file-type.lisp (file)
Next: Exported conditions, Previous: Exported functions, Up: Exported definitions [Contents][Index]
Builds HTML documentation for ASDF system and returns absolute path to the dir with docs.
file-type.lisp (file)
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:find-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:find-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/"))))
“‘
file-type.lisp (file)
file-type.lisp (file)
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.
file-type.lisp (file)
file-type.lisp (file)
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.
file-type.lisp (file)
Previous: Exported generic functions, Up: Exported definitions [Contents][Index]
file-type.lisp (file)
error (condition)
num-of-warnings (method)
:num-of-warnings
num-of-warnings (generic function)
Previous: Exported definitions, Up: Definitions [Contents][Index]
| • Internal special variables | ||
| • Internal functions |
Next: Internal functions, Previous: Internal definitions, Up: Internal definitions [Contents][Index]
file-type.lisp (file)
file-type.lisp (file)
file-type.lisp (file)
file-type.lisp (file)
file-type.lisp (file)
file-type.lisp (file)
file-type.lisp (file)
file-type.lisp (file)
file-type.lisp (file)
file-type.lisp (file)
file-type.lisp (file)
file-type.lisp (file)
file-type.lisp (file)
file-type.lisp (file)
file-type.lisp (file)
file-type.lisp (file)
file-type.lisp (file)
file-type.lisp (file)
file-type.lisp (file)
file-type.lisp (file)
file-type.lisp (file)
file-type.lisp (file)
file-type.lisp (file)
file-type.lisp (file)
file-type.lisp (file)
file-type.lisp (file)
file-type.lisp (file)
file-type.lisp (file)
file-type.lisp (file)
file-type.lisp (file)
file-type.lisp (file)
file-type.lisp (file)
file-type.lisp (file)
file-type.lisp (file)
file-type.lisp (file)
file-type.lisp (file)
file-type.lisp (file)
file-type.lisp (file)
file-type.lisp (file)
file-type.lisp (file)
Previous: Internal special variables, Up: Internal definitions [Contents][Index]
file-type.lisp (file)
Returns either a string or nil if this item should be skipped.
ITEM can be a string or a list like:
(:feature :windows "winhttp")
file-type.lisp (file)
file-type.lisp (file)
file-type.lisp (file)
Previous: Definitions, Up: Top [Contents][Index]
| • Concept index | ||
| • Function index | ||
| • Variable index | ||
| • Data type index |
Next: Function index, Previous: Indexes, Up: Indexes [Contents][Index]
| Jump to: | D F L |
|---|
| Jump to: | D F L |
|---|
Next: Variable index, Previous: Concept index, Up: Indexes [Contents][Index]
| Jump to: | 4
B D E F G M N S |
|---|
| Jump to: | 4
B D E F G M N S |
|---|
Next: Data type index, Previous: Function index, Up: Indexes [Contents][Index]
| Jump to: | *
0
@
N S |
|---|
| Jump to: | *
0
@
N S |
|---|
Previous: Variable index, Up: Indexes [Contents][Index]
| Jump to: | C D P S |
|---|
| Jump to: | C D P S |
|---|