shdoc is a documentation generator for bash/zsh/sh for generating API documentation in Markdown from shell scripts source.
shdoc parses annotations in the beginning of a given file and alongside function definitions, and creates a markdown file with ready to use documentation.
|
Generate documentation with the following command: $ shdoc < lib.sh > doc.mdSource examples/readme-example.sh #!/bin/bash
# @file libexample
# @brief A library that solves some common problems.
# @description
# The project solves lots of problems:
# * a
# * b
# * c
# * etc
# @description My super function.
# Not thread-safe.
#
# @example
# echo "test: $(say-hello World)"
#
# @arg $1 string A value to print
#
# @exitcode 0 If successful.
# @exitcode 1 If an empty string passed.
#
# @see validate()
say-hello() {
if [[ ! "$1" ]]; then
return 1;
fi
echo "Hello $1"
} |
# libexample
A library that solves some common problems.
## Overview
The project solves lots of problems:
* a
* b
* c
* etc
## Index
* [say-hello()](#say-hello)
### say-hello()
My super function.
Not thread-safe.
#### Example
```bash
echo "test: $(say-hello World)"
```
#### Arguments
* **$1** (string): A value to print
#### Exit codes
* **0**: If successful.
* **1**: If an empty string passed.
#### See also
* [validate()](#validate) |
A name of the project, used as a title of the doc. Can be specified once in the beginning of the file.
Example
#!/bin/bash
# @name MyLibraryA brief line about the project. Can be specified once in the beginning of the file.
Example
#!/bin/bash
# @brief A library to solve a few problems.A multiline description of the project/function.
- Can be specified once for the whole file in the begibeginning of the file.
- Can be specified once for on top of a function definition.
Example
#!/bin/bash
# @description A long description of the library.
# Second line of the project description.
# @description My super function.
# Second line of my super function description.
function super() {
...
}A multiline example of the function usage. Can be specified only alongside the function definition.
Example
# @example
# echo "test: $(say-hello World)"
say-hello() {
...
}A description of an argument expected to be passed while calling the function. Can be specified multiple times to describe any number of arguments.
Example
# @description Says hi to a given person.
# @arg $1 string A person's name.
# @arg $2 string Message priority.
say-hello() {
...
}A note that the function does not expect any arguments to be passed.
Example
# @description Says 'hello world'.
# @noargs
say-hello-world() {
...
}Describes an expected exitcode of the function. Can be specified multiple times to describe all possible exitcodes and their conditions.
Example
# @description Says 'hello world'.
# @exitcode 0 If successful.
# @exitcode 1 If world is gone.
say-hello-world() {
...
}An expected output of the function call.
Example
# @description Says 'hello world'.
# @stdout A path to a temporary file with the message.
say-hello-world() {
...
}Create a link on the given function in the See Also section.
Example
# @see say-hello
say-hello-world() {
...
}When you want to skip documentation generation for a particular function, you can specify this
@internal tag.
It allows you to have the same style of doc comments across the script and keep internal
functions hidden from users.
Example
# @internal
show-msg() {
...
}shdoc has no args and expects a shell script with comments on stdin and will produce markdown as stdout.
$ shdoc < your-shell-script.sh > doc.mdArch Linux users can install shdoc using package in AUR: shdoc-git
NOTE: shdoc requires gawk: apt-get install gawk or brew install gawk
git clone --recursive https://github.com/snowplow-devops/shdoc
cd shdoc
sudo make installUnfortunately, there are no packages of shdoc for other distros, but we're looking for contributions.
See example documentation on:
MIT