Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/pyrmont/documentarian
A document generation tool for Janet projects
https://github.com/pyrmont/documentarian
documentation janet markdown
Last synced: about 2 months ago
JSON representation
A document generation tool for Janet projects
- Host: GitHub
- URL: https://github.com/pyrmont/documentarian
- Owner: pyrmont
- License: mit
- Created: 2020-05-09T19:26:46.000Z (over 4 years ago)
- Default Branch: master
- Last Pushed: 2023-08-13T06:33:02.000Z (about 1 year ago)
- Last Synced: 2024-06-08T10:32:28.725Z (3 months ago)
- Topics: documentation, janet, markdown
- Language: Janet
- Homepage:
- Size: 97.7 KB
- Stars: 17
- Watchers: 3
- Forks: 2
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Documentarian
[![Build Status][icon]][status]
[icon]: https://github.com/pyrmont/documentarian/workflows/build/badge.svg
[status]: https://github.com/pyrmont/documentarian/actions?query=workflow%3Abuild
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.
## Installing
To install, run:
```console
$ jpm install https://github.com/pyrmont/documentarian
```
## Usage
```console
$ /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][ls] in addition to regular `"`-delimited strings. Long strings
preserve whitespace (including newlines) which can be used to create lists,
headings and code blocks.
[ls]: https://janet-lang.org/docs/strings.html
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][mustache]. Documentarian processes the template using
[Musty][]. Please note that Musty is an incomplete implementation and does not
support the more advanced features of Mustache.
[mustache]: http://mustache.github.io
[Musty]: https://github.com/pyrmont/musty
### Command-Line Arguments
Documentarian supports the following command-line arguments:
```
-d, --defix Remove from all namespaces.
-L, --link-prefix Use as prefix for source code links.
-x, --exclude Exclude bindings in from the API document.
-P, --private Include private values in the API document.
-p, --project Use as project file. (Default: project.janet)
-l, --local Set Janet's syspath to ./jpm_tree.
-t, --tree Set Janet's syspath to .
-e, --echo Output to stdout rather than output file.
-o, --out Use as filename for the API document. (Default: api.md)
-T, --template Use as template for the API document.
-h, --help Show this help message.
```
## Development
### Preparing
Clone the repository and then run:
```console
$ jpm [-l] run dev-deps
```
### Building
```console
$ jpm [-l] build
```
### Testing
```console
$ jpm [-l] test
```
## Bugs
Found a bug? I'd love to know about it. The best way is to report your bug in
the [Issues][] section on GitHub.
[Issues]: https://github.com/pyrmont/documentarian/issues
## Licence
Documentarian is licensed under the MIT Licence. See [LICENSE][] for more
details.
[LICENSE]: https://github.com/pyrmont/documentarian/blob/master/LICENSE
## Thanks
Special thanks to Andrew Chambers ([@andrewchambers][]) and Zach Smith
([@subsetpark][]) for their feedback and suggestions.
[@andrewchambers]: https://github.com/andrewchambers
[@subsetpark]: https://github.com/subsetpark