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.mdSourceexamples/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" ]];thenreturn 1;fiecho"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```bashecho"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.functionsuper() {
...
}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'.# @noargssay-hello-world() {
...
}A description of a global variable that is set while calling the function. Can be specified multiple times to describe any number of variables
Example
# @description Sets hello to the variable REPLY# @set REPLY string Greeting message.set-hello() {
...
}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-hellosay-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
# @internalshow-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
git clone --recursive https://github.com/reconquest/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