Generate documentation for your Fennel project.
For your.fnl
:
;;;; Your module description.
(fn hello []
"Say hello."
(print :hello))
(fn good-bye []
"Say good bye. See also `hello'."
(print :good-bye))
{: hello : good-bye}
Run fnldoc your.fnl
, and you'll get doc/your.md
:
# Your.fnl
Your module description.
**Table of contents**
- Function: [good-bye](#function-good-bye)
- Function: [hello](#function-hello)
## Function: good-bye
```fennel
(good-bye)
```
Say good bye. See also [`hello`](#function-hello).
## Function: hello
```fennel
(hello)
```
Say hello.
<!-- Generated with Fnldoc 1.1.0-dev
https://sr.ht/~m15a/fnldoc/ -->
Fnldoc is a fork of now archived Fenneldoc, with some bug fixes and new features. It automatically generates Markdown documentation from Fennel source code. It searches for function metadata and documentation comments in source code, and then formats these pieces of information into API documentation. In addition, it can test Fennel code inside Markdown fences in function docstring (a.k.a. doctest).
;;;;
. `text'
enclosed by backtick and single
quote is turned into internal hyperlink.Bold texts are major enhancements contributed by this fork.
Take a look at CHANGELOG.md
to find fixed bugs
and minor enhancements.
To build and install Fnldoc, you need the following dependencies.
Clone this repository and run make install
:
$ git clone https://git.sr.ht/~m15a/fnldoc
$ cd fnldoc
$ make install PREFIX=$YOUR_FAVORITE_PATH
Alternative ways for installation:
fnldoc [OPTIONS] [FILE]...
Markdown documentation will be generated in ./doc
directory (default).
Fnldoc generates documentation from three sources of information:
For writing documentation in source 1, see the following four sections, Function docstring, Macro dosctring, Keep function or macro private, and Specifying order of contents. For source 2, see Module top-level comments. For source 3, see Copyright, license, and version. Finally, to generate internal links in documentation, see Inline reference.
[!WARNING] For source 1, Fnldoc runs your code by executing
fennel.dofile
, and collects runtime information such as metadata and exported functions. It does so in a restricted environment called sandbox, so if your program has any side effects reachable during file loading, you will get an error. Use--no-sandbox
flag in command line or:sandbox
option in configuration file to override this behavior (see Configuration).
Write docstring as usual, then Fnldoc generates description for the function (or macro) accordingly. For example,
(fn your-function [...]
"`your-function`'s docstring."
(print ...))
{: your-function}
The above function will get its section in documentation:
## Function: your-function
```fennel
(your-function ...)
```
`your-function`'s docstring.
If you write Markdown code fence inside docstring, it can be validated by Fnldoc. See Test documentation for more details.
Macros defined in a macro module, which may be imported by
import-macros
, are automatically shown as macros in documentation:
## Macro: your-macro
```fennel
(your-macro ...)
```
`your-macro`'s docstring.
If this does not suffice, you can explicitly annotate macros
using Fnldoc's metadata field :fnldoc/type
:
(fn your-macro [...]
"`your-macro`'s docstring."
{:fnldoc/type :macro}
`(print ...))
{: your-macro}
As well as function docstring, Markdown code fence inside macro docstring can also be validated. See Test documentation for more details.
To generate documentation, Fnldoc searches for metadata inside code
recursively, meaning that functions or macros contained in any table
exposed in a module will be documented. However, sometimes you may not
want a function or macro to be documented. To prevent them from being
documented, you can specify metadata field :fnldoc/type
as :private
.
For example,
(local exposed-table {})
(fn exposed-table.private-function [...]
{:fnldoc/type :private}
(do :something))
{: exposed-table}
Fnldoc supports specifying order of items by passing a sequential
table of item names to :order
option. For example, suppose we have a
module with two functions:
(fn first-function [...]
(do :first-thing))
(fn another-function [...]
(do :another-thing))
{: first-function : another-function}
Fnldoc sorts the table alphabetically by default, thus the order of
the documentation will be another-function
followed by
first-function
. You can override this behavior for the file in
.fenneldoc
by specifying the file's :order
option in the
:modules-info
table:
{:modules-info
{"path/to/the/file.fnl" {:order [:first-function
:another-function]}}}
In addition, you can specify :order
option as either
:reverse-alphabetic
, or a custom comparator function. The latter will
be passed to Lua's table.sort
function as its third argument.
You can also set this in command line via --order
flag (see
Configuration). Note that you can't pass sorting
function or table via command-line argument; only alphabetic
or
reverse-alphabetic
.
Fnldoc collects runtime information for generating documentation.
Meanwhile, it reads Fennel code as text file and searches for module
top-level comment lines beginning with four semicolons, ;;;;
, which
will be inserted to documentation as module-wide description. For
example, the following module file
;;;; Your module.
;;;; A line.
;;;;
;; This is usual comment.
;;;; Another line.
(fn fun []
(do :something))
;;;; Here will be ignored as it's apart from the above top-level lines.
{: fun}
will get its Markdown documentation:
# Your-module.fnl
Your module.
A line.
Another line.
**Table of contents**
- Function: [fun](#function-fun)
## Function: fun
```fennel
(fun)
```
**Undocumented**
[!NOTE] Unlike function or macro docstring, Markdown code fences inside module top-level comments will not be validated for now.
You can add a footer section containing author name, copyright, and license information via configuration (see Configuration). You can also specify project version or module version in configuration. The specified version will be inserted into Markdown level-1 heading at the top of documentation file.
Configuration may be project-wide,
{:project-copyright "Copyright (C) 20XX Your Name"
:project-version "1.x.x"
:project-license "[YOUR_LICENSE](link to your license file/URL)"}}}
or module-wide
{:modules-info
{"my-module.fnl"
{:copyright "Copyright (C) 20XX Your Name"
:version "1.x.x"
:license "[YOUR_LICENSE](link to your license file/URL)"}}}
Fnldoc supports inline reference (i.e., internal link) by Fnldoc's
special syntax: any text surrounded by a backtick (`
) and a single
quote ('
) will be converted to an internal link if the text refers to
any exported function or macro name. If any appropriate heading to be
referenced is not found, it falls back to plain `code`
.
For example, function bar
in the following module has an inline
reference to function foo
.
(fn foo [...]
(print ...))
(fn bar [...]
"See `foo'."
(foo ...))
{: foo : bar}
Fnldoc generates an internal link to foo
as follows.
**Table of contents**
- Function: [bar](#function-bar)
- Function: [foo](#function-foo)
## Function: bar
```fennel
(bar ...)
```
See [`foo`](#function-foo).
## Function: foo
```fennel
(foo ...)
```
**Undocumented**
Whether to replace inline references with links can be customized by
:mode
option (see Configuration).
Fnldoc understands Markdown code fences with fennel
annotation as
test code to be validated, and run these tests unless the code fences
also have :skip-test
annotation. For example, suppose we made a change
in function but forgot to update the docstring:
(fn sum [a b]
"Sums three arguments.
# Examples
``` fennel
(assert (= (sum 1 2 3) 6))
```"
(+ a b))
{: sum}
This function claims that it sums three arguments, however the actual
body only sums two. If we run fnldoc --mode check sum.fnl
, we'll get
the following:
$ fnldoc --mode check sum.fnl
fnldoc [WARNING]: in file 'sum.fnl' function 'sum' has undocumented argument 'a'
fnldoc [WARNING]: in file 'sum.fnl' function 'sum' has undocumented argument 'b'
fnldoc [ERROR]: In file: 'sum.fnl'
Error in docstring for: 'sum'
In test:
``` fennel
(assert (= (sum 1 2 3) 6))
```
Error:
assertion failed!
fnldoc [ERROR]: errors in file 'sum.fnl'
On the other hand with :skip-test
annotation,
(fn sum [a b]
"Sums three arguments.
# Examples
``` fennel :skip-test
(assert (= (sum 1 2 3) 6))
```"
(+ a b))
{: sum}
the failing test will be skipped:
$ fnldoc --mode check sum.fnl
fnldoc [WARNING]: in file 'sum.fnl' function 'sum' has undocumented argument 'a'
fnldoc [WARNING]: in file 'sum.fnl' function 'sum' has undocumented argument 'b'
fnldoc [INFO]: skipping test in 'sum'
By the way, did you notice that Fnldoc warned when finding undocumented arguments?
fnldoc [WARNING]: in file 'sum.fnl' function 'sum' has undocumented argument 'a'
In most cases Fnldoc is smart enough, and can require your module's
exported functions automatically. However, if this doesn't work, you
can specify how dependencies should be required in .fenneldoc
configuration. Macro modules are such cases, and you'll have to teach
Fnldoc a proper require for your macro modules. For example,
{:test-requirements
{:path/to/macros.fnl "(import-macros {: a-macro} :path.to.macros)"}}
Run fnldoc --help
and you'll find configuration options that can be
customized by command line flags. If you like to configure options
permanently, write out your configuration in .fenneldoc
file. Fnldoc
looks for .fenneldoc
in your current directory and set options
accordingly.
.fenneldoc
should return a table of option settings. It looks
like so:
{:out-dir "./doc"
:src-dir "./lib"
:mode :doc
:toc? false
:function-signatures? true
:inline-references :code
:order "alphabetic"
:modules-info
{"lib/module.fnl" {:order :reverse-alphabetic}}
:test-requirements
{"lib/module.fnl" "(import-macros {: great-macro} :your-macros)"}
:project-copyright "YOUR NAME"
:project-license "LICENSE"
:project-version "VERSION"
:sandbox? false}
You can generate .fenneldoc
filled with defaults by invoking
fnldoc --config
. If you want to generate a fresh .fenneldoc
, remove
old .fenneldoc
and run fnldoc --config
again. If you want to
override configuration options in .fenneldoc
, pass flags to fnldoc
like this:
$ fnldoc --no-toc --no-function-signatures --config
This will disable table of contents and function signatures in
generated .fenneldoc
.
A full description of configuration options can be found in
doc/fnldoc/config.md
.
Report issues or feature requests on the project's issue tracker or alternatively on GitHub issues. Send a patch to the project's mailing list or create a pull request on GitHub. All contributions are welcome and highly appreciated.
Copyright (c) 2020 Andrey Orst, 2024 NACAMURA Mitsuhiro. Unless otherwise stated, this software is distributed under the MIT license.
test/faith.fnl
is copyright (c) 2009-2024
Scott Vokes, Phil Hagelberg, and contributors, distributed under
the MIT license. See the license paragraphs at the beginning of
the file.