reconquest / Shdoc
Programming Languages
shdoc
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.
Index
Example
|
Generate documentation with the following command: $ shdoc < lib.sh > doc.md
Source 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)
|
Features
@name
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 MyLibrary
@brief
A 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.
@description
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() {
...
}
@example
A multiline example of the function usage. Can be specified only alongside the function definition.
Example
# @example
# echo "test: $(say-hello World)"
say-hello() {
...
}
@arg
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() {
...
}
@noargs
A note that the function does not expect any arguments to be passed.
Example
# @description Says 'hello world'.
# @noargs
say-hello-world() {
...
}
@exitcode
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() {
...
}
@stdout
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() {
...
}
@see
Create a link on the given function in the See Also section.
Example
# @see say-hello
say-hello-world() {
...
}
@internal
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() {
...
}
Usage
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.md
Installation
Arch Linux
Arch Linux users can install shdoc using package in AUR: shdoc-git
Using Git
NOTE: shdoc requires gawk: apt-get install gawk
git clone --recursive https://github.com/reconquest/shdoc
cd shdoc
sudo make install
Others
Unfortunately, there are no packages of shdoc for other distros, but we're looking for contributions.
Examples
See example documentation on:
LICENSE
MIT