bashdog = bashdoc + ng

A modern, configurable, and easy-to-use documentation generator for Bash frameworks. bashdog parses structured comments in your shell scripts and generates clean, readable documentation in both Markdown and HTML formats.

Inspired by bashdoc but I needed something a bit different that suited my needs better.

• Module & Function Documentation - Group related functions into modules for better organization.
• Highly Configurable - Control parsing behavior, file discovery, and output using a simple .bashdog.yaml file. No need to touch the code.
• CLI Overrides - All key configuration options can be overridden directly from the command line for maximum flexibility.
• Multiple Output Formats - Generate documentation in Markdown, HTML, or both.
• File Exclusion - Easily exclude test files, vendor directories, or drafts from the documentation.
• Minimal Dependencies - Built with a small set of Python libraries.

You can find some generated examples in the examples/ directory.

Ensure you have Python 3 installed. You can install bashdog directly from the project root using pip.

cd /path/to/bashdog
pip install .

or

pip install git+https://github.com/TheArqsz/bashdog.git

...or just use Docker version.

This will make the bashdog command available in your terminal.

You can run bashdog using a configuration file, command-line arguments, or a combination of both.

1. Create a .bashdog.yaml file in the root of your Bash project (see the configuration section below for an example).
2. Update the source_directory in .bashdog.yaml to point to your scripts.
3. Run the tool:

bashdog

By default, this will generate a documentation.md file in a ./docs directory.

You can also run bashdog using the pre-built Docker image, which avoids the need for a local Python installation.

1. Pull the image from Docker Hub:

docker pull thearqsz/bashdog:latest

2. Run the container - the key is to mount your project directory into the container's /app working directory and use proper user id.

docker run --rm -v "$(pwd)":/app -u $(id -u) thearqsz/bashdog:latest

This command runs bashdog inside the container using the .bashdog.yaml file from your current directory. The generated docs/ folder will be created in your local project directory.

You can also pass command-line arguments:

docker run --rm -v "$(pwd)":/app -u $(id -u) thearqsz/bashdog:latest -i ./scripts -o ./output -f all

For a full list of options, run bashdog --help.

usage: bashdog [-h] [-i INPUT_DIR] [-f {html,md,all}] [--config CONFIG] [-o OUTPUT_DIR] [--extensions EXTENSIONS [EXTENSIONS ...]]
               [--exclude EXCLUDE [EXCLUDE ...]]

Bash Documentation Generator (bashdog)

options:
  -h, --help            show this help message and exit
  -i INPUT_DIR, --input INPUT_DIR
                        Path to the source directory to scan. Required if no config file is used.
  -f {html,md,all}, --format {html,md,all}
                        The output format for the documentation (default: md).
  --config CONFIG       Path to the configuration file (default: .bashdog.yaml)

Configuration Overrides:
  These arguments override settings from the .bashdog.yaml file.

  -o OUTPUT_DIR, --output OUTPUT_DIR
                        Specify the output directory.
  --extensions EXTENSIONS [EXTENSIONS ...]
                        A space-separated list of file extensions to process (e.g., .sh .bash).
  --exclude EXCLUDE [EXCLUDE ...]
                        A space-separated list of glob patterns to exclude.

This is the recommended way to use bashdog. Create a .bashdog.yaml file in your project root. The sample is below but you can find full .bashdog.yaml example in the root of this project.

project_name: "My Awesome Bash Project"

parsers:
  tag_prefix: "@"
  
  module:
    style:
      char: "="
      min_length: 10
  
  function:
    start_marker: "##!"
    end_marker: "#'"

bashdog parses two types of documentation blocks: modules and functions.

A module block provides high-level information about a script file. It is enclosed by separator lines defined in your .bashdog.yaml.

# ==============================================================================
# @module My Awesome Module
# @description
#   This module handles all the file processing operations. It provides
#   functions to read, write, and validate file formats.
#
#   Key features include:
#     - Reading CSV files.
#     - Writing JSON output.
#
# @author John Doe
# ==============================================================================

A function block describes a single function. It begins with a start_marker (##!) and can optionally end with an end_marker (#'). The block must be placed directly before the function definition.

##!
# @description
#   Reads a CSV file from the given path and returns its content.
#   This is a multi-line description that will be joined into a
#   single paragraph.
#
# @arg {string} $1 - The full path to the input CSV file.
#
# @global {boolean} VERBOSE - If true, prints extra logging.
#
# @example
#   read_csv "/path/to/my/data.csv"
#'
function read_csv() {
  local file_path="$1"
  # ... function logic ...
}

• @description: A description of the module or function. Can be multi-line.
• @arg: Describes a function argument. Format: {type} $name - Description.
• @global: Describes a global variable the function uses. Format: {type} VAR_NAME - Description.
• @example: A code example showing how to use the function.
• @author: The author of a module.
• @usage: Usage information for a module.

To set up a development environment:

1. Clone the repository.
2. Create and activate a virtual environment:

python -m venv .venv
source .venv/bin/activate

3. Install the package:

pip install .

This allows you to make changes to the source code and test them immediately without reinstalling.

To run the test suite, navigate to the project's root directory and execute the following command:

python -m unittest discover tests

This will automatically discover and run all tests located in the tests/ directory.

This project is licensed under the MIT License.

The logo used for the bashdog project was designed and generated with the assistance of Gemini, a large language model developed by Google.