Skip to content
/ bashdoc Public

The bashdoc script is a frontend which parse a bash file and create a documentation in specified format. This script works similar to javadoc for java projects, but use reStructuredText as middle language to provide the final document.

License

Notifications You must be signed in to change notification settings

ajdiaz/bashdoc

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

33 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

bashdoc

Documentation generator for bash applications.

Documentation syntax

Bashdoc will evaluate some special comments into the source code. The comments are prefixed with the following doc strings:

# mod: modname : The module name itself.

# fun: funsignature : The function signature, usually include parameters here, but not describe them.

# txt: : Textual description of the previous declarated section (module or function).

# opt: param: ... : Describe an option or parameter to a function.

# env: VAR: ... : Describe a environment variable called $VAR.

# use: ... : Provides an example of use of the function or module.

# api: ... : Set the API name for this element. The API name could be used to filter what functions or modules will be documented in final output.

Examples

Let's suppose the following content of the file script.bash

# mod: example
# txt: this module is an example for documentation.
#      The txt sections as also opt and env ones can
#      be multiline if lines are kept vertical aligned.

# fun: sum num1 num2
# txt: sum two numbers and output the result
# opt: num1: the first number to sum
# opt: num2: the second number to sum
# use: sum 1 3
# api: sum
sum ()
{
  echo "$(($1 + $2))"
}

Now you can generate the HTML with the command:

bashdoc -o doc.html script.bash

Using API name

Le'ts suppose the previous example code, and we need to add more functions there:

# fun: internal_sum num1
# txt: return zero (yes, it's not very usefull function)
# api: internal
internal_sum ()
{
  echo 0
}

If we generate the HTML in the same way that we do previously, the result HTML will contain two documented functions: sum and internal_sum, but we don't want the second one in the documentation. Of course we can remove the doc strings from there, but then we loose the documentation in the code too. To avoid this problem we can use the API name. If you look carefully, you can see that the api name in the first function is sum, and in the second one is internal. If we run bashdoc as following:

bashdoc -A sum -o doc.html script.bash

We will create documentation only for functions tagged as API sum. Please note that if you force a specific API tag, then functions or modules without declared API will be not documented.

Using custom stylesheet

By default bashdoc using its own CSS stylesheet and HTML template, which is pretty nice, by the way, but if you want to use your own style and/or HTML template, you can use it passing paramenters -s (for style) and -t (for template) to the bashdoc command.

Accepted styleshet is any file which contains valid CSS code. Accepted template is any template accepted by pandoc.

For example:

bashdoc -s mystyle.css -t mytemplate.html -o doc.html script.bash

About

The bashdoc script is a frontend which parse a bash file and create a documentation in specified format. This script works similar to javadoc for java projects, but use reStructuredText as middle language to provide the final document.

Resources

License

Stars

Watchers

Forks

Packages

No packages published