Package name |
BARUCH |
Package documentation
Writes Common Lisp documentation in asciidoc format.
documentation | |
sourcecode |
Write package and API documentation in asciidoc
format for every external symbol in a package into a single file. This text
you are reading is the package-level documentation for baruch
with the API documentation given below under Functions.
Text in documentation strings is copied directly to the output file (deindenting where necessary), and so you can use any of asciidoc’s syntax. Notice the use in this package documentation of web links, description lists, formatted text and syntax highlighting of code.
The generated documentation file can then be converted to html or pdf, embedded in another document, or some sites (e.g. github) will render adoc files directly. As the generated asciidoc text file is processed separately, documentation may include any extensions supported by the asciidoc converter program - for example, asciidoctor supports diagrams and mathematical syntax, amongst many others.
To produce the documentation for this package:
> (require :asdf) > (require :baruch) > (baruch:document-package :baruch "baruch.adoc")
For your exported symbols, write docstrings as usual, with optional asciidoc markup. For example, the docstring for DOCUMENT-PACKAGE is:
(defun document-package (pkg-name filename &key ignore-defaults numbered toc)
"* `pkg-name` - name of package to document
* `filename` - name of file to save package information into
* `ignore-defaults` - t/nil flag to not write the default values for key/optional parameters
* `numbered` - t/nil flag to number the sections (includes :sectnums: attribute)
* `toc` - t/nil flag to include table of contents (includes :toc: attribute)
Writes information on all exported symbols in given package as an asciidoc file.
Error:: if `pkg-name` is not found."
; <SNIP> IMPLEMENTATION
)
Baruch intentionally makes no attempt to link package and system documentation together into single 'web sites' or 'pdf books', leaving such arrangements to the documenter.
Install
To install baruch
, download the
latest release
and make the code available to the
asdf
system.
Depends on |
(Baruch should work with Common Lisp implementations supported by closer-mop - tested on ABCL, CLISP and SBCL.)
Examples
-
You can use
baruch
with any package: for example LTk documentation - automatically rendered by Github. -
The documentation for this package is an example where the documentation strings include asciidoc markup.
-
Asciidoc is accepted in some static-site generators, such as jekyll.
Symbol Anchors, Cross References and Links
Symbols are listed under their respective group: class, function, macro, type, or variable.
Each symbol is given an anchor which can be used to create cross-references within documentation strings or across different parts of the documentation. Each anchor is of the form NAME-GROUP, where NAME is the symbol name and GROUP is one of the above groups.
Symbol names have asterisks and plus symbols removed in the link anchor, so
the documentation for the exported variable *tk* is linked to as <<
tk-variable >>
.
Symbols can then be cross-referenced using the anchor using normal asciidoc syntax. For example, to link to baruch’s DOCUMENT-PACKAGE function:
-
internally, from within another docstring in the same package (as above!):
<<document-package-function>>
-
internally, from another page in the same website:
link:/baruch/#document-package-function[document-package]
-
externally, from a page in a different website:
https://peterlane.codeberg.page/baruch/#document-package-function[document-package]
Functions
- Lambda list
-
document-package ( pkg-name filename &key ignore-defaults numbered toc )
- Documentation
-
-
pkg-name
- name of package to document -
filename
- name of file to save package information into -
ignore-defaults
- t/nil flag to not write the default values for key/optional parameters -
numbered
- t/nil flag to number the sections (includes :sectnums: attribute) -
toc
- t/nil flag to include table of contents (includes :toc: attribute)
-
Writes information on all exported symbols in given package as an asciidoc file.
- Error
-
if
pkg-name
is not found.
- Lambda list
-
document-system ( system-name filename )
- Documentation
-
-
system-name
- name of system to document -
filename
- name of file to save system information into
-
Writes system-level information into given file in asciidoc format, including, where available: name, author, maintainer, homepage, license, version, depends-on, description and long-description.
- Error
-
if
system-name
is not found.