Namespace src/ShellDoc

Summary:
Documentation for src/ShellDoc directory
Created on:
Last updated:

src/ShellDoc

Overview

Directory src/ShellDoc

file source src/ShellDoc/fixMarkdownToc.sh

ShellDoc::fixMarkdownToc

fix markdown TOC generated by Markdown all in one vscode extension to make TOC compatible with docsify

Arguments
  • $1 (file:String): file to fix
Exit codes
  • 1: if awk fails
See also

src/ShellDoc/generateMdFileFromTemplate.sh

file source src/ShellDoc/generateMdFileFromTemplate.sh

ShellDoc::generateMdFileFromTemplate

generates markdown file from template by replacing @@@command_help@@@ by the help of the command eg: @@@test_help@@@ will be replaced by the output of the command test --help in the directory provided

Arguments
  • $1 (templateFile:String): the file to use as template
  • $2 (targetFile:String): the target file
  • $3 (fromDir:String): the directory from which commands will be searched
  • $4 (tokenNotFoundCount:&int): (passed by reference) number of tokens @@@command_help@@@ not found in the template file
  • $5 (excludeFilesPattern:String): grep exclude pattern (eg: ‘^(compile)$’) (default value: “”)
Output on stdout
  • the generated markdown with help of the matching command
Output on stderr
  • diagnostics logs

src/ShellDoc/generateShellDoc.sh

file source src/ShellDoc/generateShellDoc.sh

ShellDoc::generateShellDoc

extract shDoc from file

Arguments
  • $1 file:String
Output on stdout
  • the shell documentation in markdown format

src/ShellDoc/generateShellDocDir.sh

file source src/ShellDoc/generateShellDocDir.sh

ShellDoc::generateShellDocDir

generate shell doc file from given directory

Arguments
  • $1 dir:String
  • $2 relativeDir:String
  • $3 (targetDocFile:String): the markdown file generated using shdoc
  • $4 (weight:Int): weight for docsy index. Eg: 10 for top level, 20 for second level, etc.
  • $5 (repositoryUrl:String): base url for src file (eg:https://github.com/fchastanet/bash-tools-framework)
  • $6 (excludeFilesPattern:String): grep exclude pattern. Eg: ‘(/_.sh|/ZZZ.sh|/__all.sh)$’
Exit codes
  • 0: if file has been generated
  • 1: if file is empty or error

src/ShellDoc/generateShellDocsFromDir.sh

file source src/ShellDoc/generateShellDocsFromDir.sh

ShellDoc::generateShellDocsFromDir

generate doc + index

Arguments
  • $1 fromDir:String
  • $2 fromDirRelative:String
  • $3 docDir:String
  • $4 indexFile:String
  • $5 (repositoryUrl:String): base url for src file (eg:https://github.com/fchastanet/bash-tools-framework)
  • $6 (excludeDirectoriesPattern:String): grep exclude pattern. Eg: ‘/testsData|/_.*’
  • $7 (excludeFilesPattern:String): grep exclude pattern. Eg: ‘(/_.sh|/ZZZ.sh|/__all.sh)$’
  • $8 (indexFileTemplate:String): template file for index.

src/ShellDoc/installRequirementsIfNeeded.sh

file source src/ShellDoc/installRequirementsIfNeeded.sh

ShellDoc::installRequirementsIfNeeded

Featuring Git::cloneOrPullIfNoChanges 3 Warning(s)

install requirements to execute shdoc

Environment variables
  • BASH_FRAMEWORK_SHDOC_CHECK_TIMEOUT (int): default value 86400 (86400 seconds = 1 day)
Variables set
  • BASH_FRAMEWORK_SHDOC_INSTALLED (String): the file created when git clone succeeded
Output on stderr
  • diagnostics information is displayed
Features
  • Git::cloneOrPullIfNoChanges
Warnings
  • cloning is skipped if vendor/.shDocInstalled file exists
  • a new check is done everyday
  • repository is not updated if a change is detected
See also
Or, if you want, you can alternatively use the GitHub discussion Q&A for feedback and questions.