Skip to content

Latest commit

 

History

History
289 lines (210 loc) · 5 KB

README.md

File metadata and controls

289 lines (210 loc) · 5 KB
Raw

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
Output: examples/readme-example.md

#!/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