Skip to content

Documentation Functions

Building documentation

documentationFileCompile

Extract and build the documentation settings cache

Usage

documentationFileCompile [ --clean ] [ --git ] [ --all ] --source sourcePath [ --derive command ... -- ] [ functionName ... ] [ --help ]

Extract and build the documentation settings cache

Location: bin/build/tools/documentation.sh

Arguments

  • --clean - Flag. Optional. Clean everything and then exit.
  • --git - Flag. Optional. Do some handy git changes. (Adding/removing files)
  • --all - Flag. Optional. Do everything regardless of cache state.
  • --source sourcePath - DirectoryList. Required. Find function source code definition in this directory.
  • --derive command ... -- - CommandList. Optional. Run this command on each changed settings file to generate derived files.
  • functionName ... - String. Optional. Specific functions to compile.
  • --help - Flag. Optional. Display this help.

Reads standard input

functionName - File with function names one per line.

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

documentationFunctionCompile

Build function documentation

Usage

documentationFunctionCompile [ --force ] [ --clean ] --source codeSource [ --documentation documentationSource ] [ --all ] [ --fingerprint ] [ functionName ... ]

Extract and build the documentation settings cache and generate derived files:

  • --documentation is required for SEE: files

Internally calls documentationFileCompile.

Location: bin/build/tools/documentation.sh

Arguments

  • --force - Flag. Optional. Create files regardless of cache status.
  • --clean - Flag. Optional. Clean everything and then exit.
  • --source codeSource - DirectoryList. Required. Code source to find functions.
  • --documentation documentationSource - Directory. Documentation source to find documentation links.
  • --all - Flag. Optional. Check all functions.
  • --fingerprint - Flag. Optional. Use fingerprint to ensure results are up to date.
  • functionName ... - String. Optional. Specific functions to compile.

Reads standard input

functionName - File with function names one per line.

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

See Also

documentationFunctionsCompile

Extract and build the documentation settings cache and generate derived

Usage

documentationFunctionsCompile [ --clean ] [ --all | --stdin- Flag. Optional. Read function names from stdin for examination. ] [ --fingerprint ] --source [ --key fingerprintKey ] [ functionName ... ]

Extract and build the documentation settings cache and generate derived files

Location: bin/build/tools/documentation.sh

Arguments

  • --clean - Flag. Optional. Clean everything and then exit. --all | --stdin- Flag. Optional. Read function names from stdin for examination.
  • --fingerprint - Flag. Optional. Use fingerprint to ensure results are up to date.
  • --source - DirectoryList. Required. Lists of directories where functions are defined (:-separated)
  • --key fingerprintKey - String. Optional. Use this name to cache results in application JSON file if available.
  • functionName ... - String. Optional. Specific functions to compile.

Reads standard input

Function. Name of functions, one per line to compile if --all is not specified.

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

documentationMake

Make documentation for Bash functions

Usage

documentationMake [ --clean ] --template templateDirectory --source sourceDirectory --target targetDirectory [ --help ]

Must faster than documentationBuild and intended to replace it.

Uses cached files at BUILD_DOCUMENTATION_PATH, assumes documentation cache structure:

  • $docHome/functionName.md - Markdown documentation
  • $docHome/SEE/functionName.md - Markdown documentation for {"SEE:functionName"}
  • $docHome/functionName.sh - functionName settings
  • $docHome/env/environmentName.md - Markdown documentation for environmentName environment variable
  • $docHome/env/environmentName.sh - environmentName environment variable settings
  • $docHome/env/more/environmentName.md - Additional Markdown documentation for environmentName environment variable
  • $docHome/SEE/environmentName.md - See link to environmentName

Location: bin/build/tools/documentation.sh

Arguments

  • --clean - Flag. Optional. Erase the cache before starting.
  • --template templateDirectory - Directory. Required. Location of additional documentation template files to generate documentation.
  • --source sourceDirectory - Directory. Required. Location of documentation source markdown.
  • --target targetDirectory - Directory. Required. Location of documentation build target.
  • --help - Flag. Optional. Display this help.

Return codes

  • 0 - Success
  • 1 - Issue with environment
  • 2 - Argument error

documentationMaker

Generate documentation using source markdown and a mapping function.

Usage

documentationMaker [ --verbose ] [ --default defaultValue ] [ sourcePath ] [ targetPath ] [ mapFunction ... ]

Generate documentation using source markdown and a mapping function.

Tokens are mapped to template paths in `BUILD_DOCUMENTATION_PATH.

Location: bin/build/tools/documentation.sh

Arguments

  • --verbose - Flag. Optional. Be wordy.
  • --default defaultValue - EmptyString. Optional. Pass --default flag to mapFunction
  • sourcePath - Exists. Optional. File or directory to convert. Reads from stdin if not provided.
  • targetPath - FileDirectory. Optional. Outputs to stdout if not specified, otherwise outputs mirror.
  • mapFunction ... - Function. Optional. Mapping function to use, and any arguments.

Reads standard input

Text

Writes to standard output

Text. Tokens are mapped to template paths in `BUILD_DOCUMENTATION_PATH

Return codes

  • 0 - Success
  • 1 - Template file not found

See Also

documentationCache

Get the default cache directory for the documentation

Usage

documentationCache [ suffix ] [ --help ]

Get the default cache directory for the documentation

Location: bin/build/tools/documentation.sh

Arguments

  • suffix - String. Optional. Directory suffix - created if does not exist.
  • --help - Flag. Optional. Display this help.

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

documentationTemplate

Get an internal template name

Usage

documentationTemplate [ --help ]

Get an internal template name

Location: bin/build/tools/documentation.sh

Arguments

  • --help - Flag. Optional. Display this help.

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

Environment documentation

documentationEnvironmentMake

Build documentation files for environment variables

Usage

documentationEnvironmentMake [ --source sourcePath ] [ --template templatePath ] [ --target targetPath ] [ --clean ] [ --force ] [ --verbose ] [ --link linkURI ] [ --help ]

Build documentation for ./bin/env (or bin/build/env) directory.

Creates a cache at documentationCache

Environment template files used:

  • line.md
  • see.md
  • more.md
  • more-header.md
  • more-footer.md

Variables applied to the environment template files:

  • link name description category more type markerName

Documentation Files generated:

  • ENV_NAME.md - Documentation page for ENV_NAME
  • SEE/ENV_NAME.md - {"SEE:ENV_NAME"} content
  • env/ENV_NAME.sh - Settings extracted from environment file.
  • env/ENV_NAME.md - Documentation line for ENV_NAME
  • env/more/ENV_NAME.md - Documentation more for ENV_NAME. Only created if needed.

Documentation settings extracted:

  • name - String. Display environment name.
  • description - String. Text description of the environment variable, many lines long and can include detailed example and markup.
  • descriptionLineCount - PositiveInteger. Number of lines in the description.
  • summary - String. Short description of the environment variable.
  • category - String. Main category for this environment variable.
  • categoryId - String. Category converted to stringLowercase and spaces replaced with underscores.
  • type - Type. Data type for this environment variable.

Where ENV_NAME matches the found environment source file without the .sh.

Target templates created:

  • categories.txt
  • environmentCategoryList.md
  • environmentCategoryTotal.md
  • environmentMore.md

Location: bin/build/tools/documentation.sh

Arguments

  • --source sourcePath - Directory. Optional. Path to source environment files (*.sh files). Defaults to $(buildHome)/bin/env if not specified.
  • --template templatePath - Directory. Optional. Path for environment template files.
  • --target targetPath - Directory. Optional. Path for generated documentation files.
  • --clean - Flag. Optional. Delete any generated files amd exit.
  • --force - Flag. Optional. Force generation of files regardless of cache status.
  • --verbose - Flag. Optional. Be chatty.
  • --link linkURI - String. Optional. Sets the link variable in templates. Defaults to /env/.
  • --help - Flag. Optional. Display this help.

Return codes

  • 0 - Success
  • 1 - Issue with environment
  • 2 - Argument error

Environment

documentationEnvironmentFileParse

Convert an environment comment to environment variables

Usage

documentationEnvironmentFileParse environmentFile [ --help ]

Convert an environment comment to environment variables

Location: bin/build/tools/documentation.sh

Arguments

  • environmentFile - EnvironmentFile. Required. File to convert to a settings file.
  • --help - Flag. Optional. Display this help.

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

Documentation code management

documentationFilesAdd

Git add documentation files

Usage

documentationFilesAdd [ --help ]

Git add documentation files Just the first path.

Location: bin/build/tools/documentation.sh

Arguments

  • --help - Flag. Optional. Display this help.

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

documentationFunctionRemove

Remove a function from the documentation cache

Usage

documentationFunctionRemove [ --verbose ] [ --dry-run ] [ --git ] [ --help ]

Remove a function from the documentation cache

Location: bin/build/tools/documentation.sh

Arguments

  • --verbose - Flag. Optional. Use more words or phrases than absolutely essential.
  • --dry-run - Flag. Optional. Do not do any thing, just say what would be done.
  • --git - Flag. Remove from git.
  • --help - Flag. Optional. Display this help.

Reads standard input

functionName - File with function names one per line.

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

Markdown generation

bashDocumentationDefaults

Generate base template files for Bash code documentation.

Usage

bashDocumentationDefaults --target templateTarget [ --help ] [ --handler handler ]

Generates the following (with example content): - applicationName.md - Zesk Build - applicationOwner.md - Market Acumen, Inc. - year.md - 2026 - version.md - v0.43.2 - timestamp.md - 1779910142 - timestampString.md - 2026-05-27 15:29:15 Failure is dirty; target directory may be modified even on failure.

Location: bin/build/tools/documentation.sh

Arguments

  • --target templateTarget - FileDirectory. Required. Create templates here.
  • --help - Flag. Optional. Display this help.
  • --handler handler - Function. Optional. Use this error handler instead of the default error handler.

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

bashDocumentationDeriveFunction

Generate markdown documentation page

Usage

bashDocumentationDeriveFunction [ --help ] [ --check ] settingsFile

Generate function derived files.

File(s) are generated next to settingsFile.

  • --check checks to see if the file needs to be generated or updated. Returns 0 if up to date.

Location: bin/build/tools/documentation.sh

Arguments

  • --help - Flag. Optional. Display this help.
  • --check - Flag. Optional. Check to see if an update is needed
  • settingsFile - File. Required. Settings file for function to document.

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

bashDocumentationDeriveSee

Generate SEE markdown content

Usage

bashDocumentationDeriveSee [ --help ] [ --check ] settingsFile

Generate SEE/{"fn"}.md - Derived file generator. File is next to settingsFile; --check checks to see if the file needs to be generated or updated.

Location: bin/build/tools/documentation.sh

Arguments

  • --help - Flag. Optional. Display this help.
  • --check - Flag. Optional. Check to see if an update is needed
  • settingsFile - File. Required. Settings file for function to document.

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

bashDocumentationMissing

Generate templates of functions missing from documentation

Usage

bashDocumentationMissing --index indexPath --source sourcePath --target templateTarget

Generates:

  • missingFunctionTotal.md
  • missingFunctionList.md

in the target directory.

Location: bin/build/tools/documentation.sh

Arguments

  • --index indexPath - Directory. Required. Where to store documentation indexes for later use.
  • --source sourcePath - Directory. Required. The source
  • --target templateTarget - FileDirectory. Required. Create templates here.

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

bashDocumentationAllEnvironment

Generate markdown for a list of all functions

Usage

bashDocumentationAllEnvironment [ --help ]

Uses list of functions passed in stdin; using the SEE template. Output to allEnvironmentList.md typically.

Location: bin/build/tools/documentation.sh

Arguments

  • --help - Flag. Optional. Display this help.

Reads standard input

EnvironmentVariable. One per line.

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

bashDocumentationAllFunctions

Generate markdown for a list of all functions

Usage

bashDocumentationAllFunctions [ --help ]

Uses list of functions passed in stdin; using the SEE template. Output to allFunctionList.md typically.

Location: bin/build/tools/documentation.sh

Arguments

  • --help - Flag. Optional. Display this help.

Reads standard input

Function. Function names one per line.

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

See Hunting

documentationFunctionsListSeeUnfinished

List files with unresolved SEE: tokens in documentation path

Usage

documentationFunctionsListSeeUnfinished [ --help ] path

Generate a list of files which have unresolved SEE: tokens in the documentation path. Searches Markdown (.md) files a single level deep.

Location: bin/build/tools/documentation.sh

Arguments

  • --help - Flag. Optional. Display this help.
  • path - Directory. Required. The documentation path to examine.

Writes to standard output

File

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

documentationFunctionsSeeLoop

Interactively watch count of unresolved SEE: tokens in documentation

Usage

documentationFunctionsSeeLoop [ --help ] path

Runs an infinite loop in the console until there are zero unresolved SEE: tokens in the documentation path. Searches Markdown (.md) files a single level deep. You can fix tokens by running documentationFunctionsCompile or building the documentation which usually updates environment templates. Delays 10 seconds between checks.

Location: bin/build/tools/documentation.sh

Arguments

  • --help - Flag. Optional. Display this help.
  • path - Directory. Required. The documentation path to examine.

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

documentationFunctionsSeeDirty

Dirty documentation files with unresolved SEE: tokens in documentation path

Usage

documentationFunctionsSeeDirty [ --help ] path

Changes the modification date of the associated files such that it will be regenerated with documentationFunctionsCompile.

Location: bin/build/tools/documentation.sh

Arguments

  • --help - Flag. Optional. Display this help.
  • path - Directory. Required. The documentation path to examine.

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

See Also

Indexes

documentationIndexGenerate

Generate a function index for bash files.

Usage

documentationIndexGenerate codePath ... [ --target targetPath ] [ --verbose ]

Generate a function index for bash files.

Location: bin/build/tools/documentation.sh

Arguments

  • codePath ... - Directory. Required. OneOrMore. Path where code (.sh files) is stored (should remain identical between invocations)
  • --target targetPath - Optional. Location to store the index file, called code.index.
  • --verbose - Flag. Optional. Talk voluminously.

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

See Also

documentationIndexDocumentation

Generate the documentation index

Arguments

  • --target targetDirectory - Directory. Optional. Directory where the index will be created. Uses documentationCache if not specified.
  • documentationSource ... - Directory. OneOrMore. Documentation source path to find tokens and their definitions.
  • --verbose - Flag. Optional. Extrapolate needlessly.
  • --help - Flag. Optional. Display this help.

Return codes

  • 0 - If success
  • 1 - Issue with file generation
  • 2 - Argument error

documentationIndexLookup

Looks up information in the function index

Usage

documentationIndexLookup [ --settings ] [ --comment ] [ --source ] [ --line ] [ --combined ] [ --file ] [ matchText ]

Looks up information in the function index

Location: bin/build/tools/documentation.sh

Arguments

  • --settings - Flag. Optional. matchText is a function name. Outputs a file name containing function settings
  • --comment - Flag. Optional. matchText is a function name. Outputs a file name containing function settings
  • --source - Flag. Optional. matchText is a function name. Outputs the source code path to where the function is defined
  • --line - Flag. Optional. matchText is a function name. Outputs the source code line where the function is defined
  • --combined - Flag. Optional. matchText is a function name. Outputs the source code path and line where the function is defined as path:line
  • --file - Flag. Optional. matchText is a file name. Find files which match this base file name.
  • matchText - String. Token to look up in the index.

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

documentationIndexUnlinkedFunctions

List functions without documentation pages.

Usage

documentationIndexUnlinkedFunctions indexPath [ --help ]

List functions without documentation pages.

Location: bin/build/tools/documentation.sh

Arguments

  • indexPath - Directory. Required. Index path.
  • --help - Flag. Optional. Display this help.

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

documentationUnlinked

List unlinked functions in documentation index

Usage

documentationUnlinked [ --help ]

List unlinked functions in documentation index

Location: bin/build/tools/documentation.sh

Arguments

  • --help - Flag. Optional. Display this help.

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

Generating documentation

documentationIdenticalRepair

Map template files using our identical functionality

Usage

documentationIdenticalRepair templatePath [ --help ]

Map template files using our identical functionality

Location: bin/build/tools/documentation.sh

Arguments

  • templatePath - Directory. Required. Path to the templates to repair.
  • --help - Flag. Optional. Display this help.

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

documentationTemplateCompile

Document an item and generate a template (markdown). To custom

Usage

documentationTemplateCompile template settingsFile

Document an item and generate a template (markdown). To custom format any of the fields in this, write functions in the form _documentationTemplateFormatter_${"name"} such that name matches the variable name (lower case alphanumeric characters and underscores).

Filter functions should modify the input/output pipe.

Location: bin/build/tools/documentation.sh

Arguments

  • template - Required. A markdown template to use to map values. Post-processed with markdownRemoveUnfinishedSections
  • settingsFile - Required. Settings file to be loaded.

Return codes

  • 0 - Success
  • 1 - Template file not found

documentationTemplateFunctionCompile

Generate a function documentation block using functionTemplate for functionName

Usage

documentationTemplateFunctionCompile [ --env-file envFile ] functionName functionTemplate [ --help ]

Requires function indexes to be generated in the documentation cache.

Generate documentation for a single function.

Template is output to stdout.

Location: bin/build/tools/documentation.sh

Arguments

  • --env-file envFile - File. Optional. One (or more) environment files used during map of functionTemplate
  • functionName - Required. The function name to document.
  • functionTemplate - Required. The template for individual functions.
  • --help - Flag. Optional. Display this help.

Return codes

  • 0 - If success
  • 1 - Issue with file generation
  • 2 - Argument error

{documentationTemplateFileCompile}

{documentationTemplateDirectoryCompile}

mkdocs Tools

mkdocs is an excellent documentation generation tool written in Python to convert Markdown to documentation.

documentationMkdocs

mkdocs Utility

Usage

documentationMkdocs [ --path documentationPath ] [ --template yamlTemplate ] [ --package packageName ] [ --version version ] [ --clean ] [ --help ]

Build documentation using mkdocs and a template.

Location: bin/build/tools/mkdocs.sh

Arguments

  • --path documentationPath - Directory. Optional. Directory where documentation root exists.
  • --template yamlTemplate - File. Optional. Name of mkdocs.yml template file to generate final file. Default is mkdocs.template.yml.
  • --package packageName - String. Optional. Install this python package when setting up mkdocs.
  • --version version - String. Optional. Use this for current version of documentation; defaults to hookVersionCurrent
  • --clean - Flag. Optional. Clean the python virtual environment first.
  • --help - Flag. Optional. Display this help.

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

See Also

Finding documentation

bashDocumentationExtract

Extract documentation from bash commentsGenerate a set of name/value pairs to document bash entities

Usage

bashDocumentationExtract [ --generate ] [ --no-cache | --cache ] [ --help ] [ --function | --environment ] itemName sourceFile [ sourceLine ]

Extract documentation variables from a comment stripped of the # prefixes.

A few special values are generated/computed:

  • description - Any line in the comment which is not in variable is appended to the field description
  • original - itemName unmodified
  • fn - The function name (no parenthesis or anything) (can be changed from itemName)
  • base - The basename of the file
  • file - The relative path name of the file from the application root
  • summary - Defaults to first ten words of description
  • exit_code - Defaults to standard value
  • reviewed - No default
  • `environment" - No default
  • usage - Computed based on arguments

Otherwise the assumed variables (in addition to above) to define functions are:

  • argument - Individual arguments
  • example - An example of usage (code, many)
  • depends - Any dependencies (list)

Location: bin/build/tools/documentation.sh

Arguments

  • itemName - String. Required. Name of item we are documenting. Usually a function name or environment variable name.
  • sourceFile - File. Required.
  • sourceLine - PositiveInteger. Optional. The line in the source file where the item is defined.
  • --generate - Flag. Optional. Generate cached files.
  • --no-cache - Flag. Optional. Skip any attempt to cache anything.
  • --cache - Flag. Optional. Force use of cache.
  • --function - Flag. Optional. Function derivations return_code fn lowerFn fnMarker argument usage
  • --environment - Flag. Optional. Environment variable derivations env envMarker
  • --help - Flag. Optional. Display this help.

Reads standard input

Pipe stripped comments to extract information

Debugging settings

Append to the value of BUILD_DEBUG (a comma-delimited (,) list) and add these tokens to enable debugging:

  • usage-cache-skip - Skip caching by default (override with --cache)

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

See Also

Usage Utilities

bashDocumentation

Universal function documentation

Arguments

  • functionDefinitionFile - File. Required. The file in which the function is defined. If you don't know, use __bashDocumentation_FindFunctionDefinitions or __bashDocumentation_FindFunctionDefinition. (Both SLOW!)
  • functionName - String. Required. The function which actually defines our usage syntax. Documentation is extracted from this function, regardless.
  • returnCode - Integer. Required. The return code to output.
  • message - String. Optional. A message to output relating to the return code.

Debugging settings

Append to the value of BUILD_DEBUG (a comma-delimited (,) list) and add these tokens to enable debugging:

  • fast-usage - bashDocumentation does not output formatted help for performance reasons
  • usage-cache-skip - Skip all caching and generate from scratch
  • handler - For all --help and any function which uses usageTemplate to output documentation (upon error), the stack will be displayed

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

Environment

Build Documentation

{buildDocumentationBuild}

🛠️ Tools · ⬅ Top