Skip to content

Documentation Functions

⬅ Parent

Building documentation

documentationBuild

Build documentation for Bash functions

Usage

documentationBuild [ --git ] [ --commit ] [ --force ] [ --unlinked ] [ --unlinked-update ] [ --clean ] [ --help ] [ --company companyName ] [ --company-link companyLink ] [ --unlinked-source directory ] [ --page-template pageTemplateFile ] --source sourceDirectory --target targetDirectory [ --function-template functionTemplateFile ] [ --unlinked-template unlinkedTemplateFile ] [ --unlinked-target unlinkedTarget ] [ --see-prefix seePrefix ] [ --see-update ] [ --unlinked-update ] [ --index-update ] [ --docs-update ]

Build documentation for Bash functions

Given that bash is not an ideal template language, caching is mandatory.

Uses a cache at buildCacheDirectory

Return Code: 0 - Success Return Code: 1 - Issue with environment Return Code: 2 - Argument error

Arguments

  • --git - Merge current branch in with docs branch
  • --commit - Commit docs to non-docs branch
  • --force - Force generation, ignore cache directives
  • --unlinked - Show unlinked functions
  • --unlinked-update - Update unlinked document file
  • --clean - Erase the cache before starting.
  • --help - I need somebody
  • --company companyName - Optional. Company name (uses BUILD_COMPANY if not set)
  • --company-link companyLink - Optional. Company name (uses BUILD_COMPANY_LINK if not set)
  • --unlinked-source directory - Directory. Optional.
  • --page-template pageTemplateFile - File. Optional.
  • --source sourceDirectory - Directory. Required. Location of source code. Can specify one or more.
  • --target targetDirectory - Directory. Required. Location of documentation build target.
  • --function-template functionTemplateFile - File. Optional.
  • --unlinked-template unlinkedTemplateFile - File. Optional.
  • --unlinked-target unlinkedTarget - FileDirectory. Optional.
  • --see-prefix seePrefix - EmptyString. Optional.
  • --see-update - Flag. Optional. Update the see indexes only.
  • --unlinked-update - Flag. Optional. Update the unlinked file only.
  • --index-update - Flag. Optional. Update the documentation indexes only.
  • --docs-update - Flag. Optional. Update the documentation target only.

Return codes

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

documentationBuildCache

Get the cache directory for the documentation

Usage

documentationBuildCache [ suffix ]

Get the cache directory for the documentation

Arguments

  • suffix - String. Optional. Directory suffix - created if does not exist.

Return codes

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

documentationBuildEnvironment

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

Usage

documentationBuildEnvironment [ --documentation documentationPath ] [ --source sourcePath ]

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

Creates a cache at documentationBuildCache

Return Code: 0 - Success Return Code: 1 - Issue with environment Return Code: 2 - Argument error

Arguments

  • --documentation documentationPath - Directory. Optional. Path to documentation root. Default is ./documentation/source.
  • --source sourcePath - Directory. Optional. Path to source environment files. Defaults to $(buildHome)/bin/env if not specified.

Return codes

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

documentationTemplate

Get an internal template name

Usage

documentationTemplate

Get an internal template name

Arguments

  • none

Return codes

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

Indexes

documentationIndexDocumentation

Generate the documentation index (e.g. functions defined in the documentation)

Usage

documentationIndexDocumentation cacheDirectory [ documentationSource ... ] [ --help ]

Generate the documentation index (e.g. functions defined in the documentation) Return Code: 0 - If success Return Code: 1 - Issue with file generation Return Code: 2 - Argument error

Arguments

  • cacheDirectory - Required. Cache directory where the index will be created.
  • documentationSource ... - OneOrMore. Documentation source path to find tokens and their definitions.
  • --help - Optional. Flag. Display this help.

Return codes

  • 0 - Success
  • 1 - Environment error
  • 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

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

documentationUnlinked

List unlinked functions in documentation index

Usage

documentationUnlinked

List unlinked functions in documentation index

Arguments

  • none

Return codes

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

Generating documentation

documentationTemplateUpdate

Map template files using our identical functionality

Usage

documentationTemplateUpdate templatePath repairPath

Map template files using our identical functionality

Arguments

  • none

Return codes

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

documentationTemplateCompile

Convert a template file to a documentation file using templates

Usage

documentationTemplateCompile [ --env-file envFile ] cacheDirectory documentTemplate functionTemplate templateFile targetFile

Convert a template which contains bash functions into full-fledged documentation.

The process:

  1. documentTemplate is scanned for tokens which are assumed to represent Bash functions
  2. functionTemplate is used to generate the documentation for each function
  3. Functions are looked up in cacheDirectory using indexing functions and
  4. Template used to generate documentation and compiled to targetFile

cacheDirectory is required - build an index using documentationIndexIndex prior to using this.

Return Code: 0 - If success Return Code: 1 - Issue with file generation Return Code: 2 - Argument error

Arguments

  • --env-file envFile - Optional. File. One (or more) environment files used to map documentTemplate prior to scanning, as defaults prior to each function generation, and after file generation.
  • cacheDirectory - Required. Cache directory where the indexes live.
  • sourceFile - Required. The document template containing functions to define
  • functionTemplate - Required. The template for individual functions defined in the documentTemplate.
  • targetFile - Required. Target file to generate

Return codes

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

Requires

catchEnvironment timingStart throwArgument usageArgumentFile usageArgumentDirectory usageArgumentFileDirectory basename decorate statusMessage fileTemporaryName rm grep cut source mapTokens returnClean mapEnvironment shaPipe printf

documentationTemplateFunctionCompile

Generate a function documentation block using functionTemplate for functionName

Usage

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

Requires function indexes to be generated in the documentation cache.

Generate documentation for a single function.

Template is output to stdout.

Return Code: 0 - If success Return Code: 1 - Issue with file generation Return Code: 2 - Argument error

Arguments

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

Return codes

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

documentationTemplateDirectoryCompile

Convert a directory of templates into documentation for Bash functions

Usage

documentationTemplateDirectoryCompile cacheDirectory documentDirectory functionTemplate targetDirectory

Convert a directory of templates for bash functions into full-fledged documentation.

The process:

  1. documentDirectory is scanned for files which look like *.md
  2. documentationTemplateDirectoryCompile is called for each one

If the cacheDirectory is supplied, it's used to store values and hashes of the various files to avoid having to regenerate each time.

Return Code: 0 - If success Return Code: 1 - Any template file failed to generate for any reason Return Code: 2 - Argument error

Arguments

  • --filter filterArgs ... -- - Arguments. Optional. Passed to find and allows filtering list.
  • --force - Flag. Optional. Force generation of files.
  • --verbose - Flag. Optional. Output more messages.
  • --env-file envFile - Optional. File. One (or more) environment files used during map of functionTemplate
  • cacheDirectory - Required. The directory where function index exists and additional cache files can be stored.
  • documentDirectory - Required. Directory containing documentation templates
  • templateFile - Required. Function template file to generate documentation for functions
  • targetDirectory - Required. Directory to create generated documentation

Return codes

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

mkdocs Tools

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

documentationMkdocs

Build documentation using mkdocs and a template

Usage

documentationMkdocs [ --path documentationPath ] [ --template yamlTemplate ]

Build documentation using mkdocs and a template

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.

Return codes

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

Finding documentation

bashDocumentationExtract

Generate a set of name/value pairs to document bash functions

Usage

bashDocumentationExtract function

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
  • fn - The function name (no parenthesis or anything)
  • 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 0 - Always succeeds
  • reviewed - Defaults to Never
  • environment" - Defaults toNo environment dependencies or modifications.`

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

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

Reads standard input

Pipe stripped comments to extract information

Arguments

  • function - String. Required. Function defined in file

Return codes

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

Usage Utilities

usageDocument

Universal error handler for functions (with formatting)

Arguments

  • functionDefinitionFile - Required. File. The file in which the function is defined. If you don't know, use __bashDocumentation_FindFunctionDefinitions or __bashDocumentation_FindFunctionDefinition.
  • functionName - Required. String. The function which actually defines our usage syntax. Documentation is extracted from this function, regardless.
  • exitCode - Required. Integer. The function which actually defines our usage syntax. Documentation is extracted from this function, regardless.
  • message - Optional. String. A message.

Debugging settings

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

  • fast-usage - usageDocument does not output formatted help for performance reasons
  • 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_DEBUG - Add fast-usage to make this quicker when you do not care about usage/failure.

Build Documentation

Arguments

  • --none - Flag. Turn off all updates.
  • --templates-only - Flag. Just template identical updates.
  • --templates - Flag. Enable template updates.
  • --no-templates - Flag. Disable template updates.
  • --derived - Flag. Enable derived files updates.
  • --no-derived - Flag. Disable derived files updates.
  • --derived-only - Flag. Just derived files only.
  • --reference - Flag. Enable reference file updates.
  • --no-reference - Flag. Disable reference file updates.
  • --reference-only - Flag. Reference file updates.
  • --mkdocs - Flag. Enable documentation generation.
  • --no-mkdocs - Flag. Disable documentation generation.
  • --mkdocs-only - Flag. Documentation generation only.
  • --see-update - Flag. Documentation generation only.
  • --index-update - Flag. Documentation generation only.
  • --docs-update - Flag. Documentation generation only.
  • --env-update - Flag. Just update env document.
  • --clean - Flag. Clean caches.
  • --verbose - Flag. Clean caches.
  • --filter filters ... - DashDashDelimitedArguments. Arguments to filter which reference files are updated.
  • --force - Flag. Force building of everything.
  • --debug - Flag. Debugging output enabled.

Return codes

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