Documentarian is a minimal documentation generation tool for Janet projects.
Documentarian makes it easy to take the docstrings you've already written for your code and turn them into a simple Markdown-formatted document. This document can be included in your repository and read easily on services like GitHub.
To install, run:
$ jpm install https://github.com/pyrmont/documentarian
$ /path/to/documentarian
Documentarian depends on your project having a project.janet
file that
contains a :name
key in the declare-project
form and a :source
key in
either the declare-source
or declare-native
forms. The :source
key can be
associated with individual files or a directory containing Janet files.
Since the API document is generated in Markdown, you can include Markdown in
your docstrings. Don't forget that Janet supports `
-delimited
long strings in addition to regular "
-delimited strings. Long strings
preserve whitespace (including newlines) which can be used to create lists,
headings and code blocks.
By default, your documentation is saved to a file called api.md
in the
current working directory. Documentarian includes a simple template that is
used to produce the api.md
file. You can specify your own template file using
the -t
command-line argument (see below). The file must be in the Mustache
templating language. Documentarian processes the template using
Musty. Please note that Musty is an incomplete implementation and does not
support the more advanced features of Mustache.
Documentarian supports the following command-line arguments:
-d, --defix <prefix> Remove <prefix> from all namespaces.
-L, --link-prefix <url> Use <url> as prefix for source code links.
-x, --exclude <path> Exclude bindings in <path> from the API document.
-P, --private Include private values in the API document.
-p, --project <path> Use <path> as project file. (Default: project.janet)
-l, --local Set Janet's syspath to ./jpm_tree.
-t, --tree <path> Set Janet's syspath to <path>.
-e, --echo Output to stdout rather than output file.
-o, --out <path> Use <path> as filename for the API document. (Default: api.md)
-T, --template <path> Use <path> as template for the API document.
-h, --help Show this help message.
Clone the repository and then run:
$ jpm [-l] run dev-deps
$ jpm [-l] build
$ jpm [-l] test
Found a bug? I'd love to know about it. The best way is to report your bug in the Issues section on GitHub.
Documentarian is licensed under the MIT Licence. See LICENSE for more details.
Special thanks to Andrew Chambers (@andrewchambers) and Zach Smith (@subsetpark) for their feedback and suggestions.