mkdocstrings-sh

A Sh handler for mkdocstrings.

This is a project unrelated to mkdocstrings-shell project. Naming it mkdocstrings-sh causes confusion with mkdocstrings-shell. I do not intent to compete with the project. Just my documentation goals are different then mkdocstrings-shell. The features and style by mkdocstrings-shell were not in line with what I wanted. I decided to write my own library. This is the result.

See the generated mkdocs pages in github pages for documentation. https://kamilcuk.github.io/mkdocstrings-sh/

See examples/ page in github pages. There are examples with all the syntax and reference of the available tags.

Installation

pip install mkdocstrings-sh

Usage:

With the following header file:

# @file script.sh
# @description this is the description
# @license this is the license
# SPDX-License-Identifier: GPL-2.0
# @author Kamil Cukrowski <kamilcukrowski at gmail.com>
# @maintainer Kamil Cukrowski <kamilcukrowski@gmail.com>

# some variable
VARIABLE=1

# Variable with default assignment
: "${ANOTHER_VAR:=1}"

# @description This is a function
# @option -a <arg> Do this
# @option -f Do that
# @option -l --longarg <arg> Do something else
# @arg $1 first arg
# @arg $2 second arg
# @arg $@ Additional arguments
# @see another_function
example_function() {}

# This is another example function
# @warning This is a warning
# @notice This is a notice
# @noargs
example_function() {}

Generate docs for this file with this instruction in one of your Markdown page:

::: path/to/script

This will generate the following HTML:

script.sh

this is the description

Author: Kamil Cukrowski <kamilcukrowski at gmail.com>

Maintainer: Kamil Cukrowski <kamilcukrowski@gmail.com>

SPDX-License-Identifier: GPL-2.0

License:

this is the license

$VARIABLE

some variable

$ANOTHER_VAR

Variable with default assignment

example_function

This is a function

Options:

• -a <arg> Do this
• -f Do that
• -l --longarg <arg> Do something else

Arguments:

• $1 first arg
• $2 second arg
• $@ Additional arguments

See: another_function

example_function

This is another example function

Warning

This is a warning

Arguments: Takes no arguments

Single entity

It is also possible to generate only a specific function, variable or a section of the file by passing additional arguments to :::. The third argument specifies the entity type. The second argument specifies the name of the function or variable or section to gneerate documeanttion for.

::: docs/examples/readme.sh function_name function
::: docs/examples/readme.sh variable_name variable
::: docs/examples/readme.sh section_name section

Feedback