{"id":16137506,"url":"https://github.com/carlinigraphy/awkdoc","last_synced_at":"2026-01-05T01:04:43.717Z","repository":{"id":161913914,"uuid":"564560622","full_name":"carlinigraphy/awkdoc","owner":"carlinigraphy","description":"Shell documentation generation from comment annotations.","archived":false,"fork":false,"pushed_at":"2024-05-19T07:10:51.000Z","size":158,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-18T16:39:57.104Z","etag":null,"topics":["awk","bash","documentation","documentation-generation","documentation-generator","documentation-tool","shell"],"latest_commit_sha":null,"homepage":"","language":"Awk","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/carlinigraphy.png","metadata":{"files":{"readme":"README.adoc","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-11-11T01:15:20.000Z","updated_at":"2024-05-19T07:10:54.000Z","dependencies_parsed_at":null,"dependency_job_id":"fff6ba7a-0010-4c5a-a759-f72184933123","html_url":"https://github.com/carlinigraphy/awkdoc","commit_stats":null,"previous_names":["carlinigraphy/awkdoc"],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/carlinigraphy%2Fawkdoc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/carlinigraphy%2Fawkdoc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/carlinigraphy%2Fawkdoc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/carlinigraphy%2Fawkdoc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/carlinigraphy","download_url":"https://codeload.github.com/carlinigraphy/awkdoc/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244900134,"owners_count":20528638,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["awk","bash","documentation","documentation-generation","documentation-generator","documentation-tool","shell"],"created_at":"2024-10-09T23:27:40.384Z","updated_at":"2026-01-05T01:04:43.657Z","avatar_url":"https://github.com/carlinigraphy.png","language":"Awk","funding_links":[],"categories":[],"sub_categories":[],"readme":"= AWKDoc\n:toc:                    preamble\n:toclevels:              3\n:source-highlighter:     pygments\n:pygments-style:         algol_nu\n:pygments-linenums-mode: table\n\nGenerates markdown documentation from comment annotations in [ba]sh source files.\n\n\n== Usage\nWrite bash, add comments with \u003c\u003cflags,annotation flags\u003e\u003e.\nRun `awkdoc` to turn annotations -\u003e markdown documentation.\n\n=== Brief example\n.input.sh\n```bash\n#!/usr/bin/env bash\n#---------------------------------------------------------\n# @section        Arithmetic functions\n# @description    Some useless functions that complicate\n#                 addition and subtraction in bash.\n#---------------------------------------------------------\n\n# @type\ndeclare -i RESULT=\n\n\n# @description\n#  Adds a number to the global RESULT.\n#\n# @set   RESULT\n# @arg   $1    :int     Number to add to the $RESULT\nfunction add {\n   (( RESULT = RESULT + $1 ))\n}\n\n\n# @description\n#  Subtracts a number from the global RESULT.\n#\n# @set   RESULT\n# @arg   $1    :int     Number to subtract from the $RESULT\nfunction sub {\n   (( RESULT = RESULT - $1 ))\n}\n```\n\nout.md\n```markdown\n# Contents.\n- [Arithmetic functions](#arithmetic-functions)\n  - [`add`](#add)\n  - [`sub`](#sub)\n\n# Types.\n|type|line|file|\n|:---|:---|:---|\n|`RESULT`|`9`|*input.sh*|\n\n# Functions.\n## Arithmetic functions\nSome useless functions that complicate\naddition and subtraction in bash.\n\n### add()\n(*ln. 17, in input.sh*)\n\nAdds a number to the global RESULT.\n\n#### args\n|name|type|desc|\n|:---|:---|:---|\n|`$1`|`:int`|Number to add to the $RESULT|\n\n### sub()\n(*ln. 27, in input.sh*)\n\nSubtracts a number from the global RESULT.\n\n#### args\n|name|type|desc|\n|:---|:---|:---|\n|`$1`|`:int`|Number to subtract from the $RESULT|\n\n\u003cbr/\u003e\u003cbr/\u003e\n:: *generated by @carlinigraphy/awkdoc* ::\n\n```\n\n\n=== Generate documentation\nRun `awkdoc`.\n\n```bash\n./awkdoc *.sh \u003e out.md\n```\n\n(Optionally) use https://github.com/jgm/pandoc[`pandoc`] to convert to .html\n\n```bash\npandoc -s out.md -o out.html --metadata title=\"documentation\"\n```\n\n*Note:* `awkdoc` does not include markdown metadata to be more generally applicable.\nThe `--metadata` flag can fill some gaps.\n\n\n=== Environment variables\nSome behavior can be modified by environment variables.\n\n[cols=\"1, 1, 3\"]\n|===\n| Variable | Acceptable values | Description\n\n| `AWKDOC_NO_COLOR`\n| `[\"\", \"yes\"]`\n| Any non-empty value will disable color in error output\n\n| `AWKDOC_LOG_LEVEL`\n| `[-1, 0, 1, 2]`\n| Higher number, more verbose. `-1` disables error reporting entirely\n|===\n\n\n== Features\nThings that make `awkdoc` nifty.\n\n\u003e *NOTE:* Instead of random examples, all the snippets below come from https://github.com/carlinigraphy/conflang[@carlinigraphy/conflang].\nHelps me to understand when looking at real life use cases.\n\n\n=== Error synchronization\nWon't fail on the first error encountered.\nCollects all possible errors \u0026 info messages before printing output.\n\n=== Error messaging\nIncludes the source file name, line number, _and original line itself_ in error output.\nEasier to see where problems occurred.\n\n.Example\n```\n==\u003e INFO: Unknown @-flag: asd\n    in test/testfile.sh\n    ln. 6: # @asd\n\n==\u003e ERROR: Missing section title\n    in test/testfile.sh\n    ln. 26: # @section\n```\n\n=== Multiline descriptions\n\u003c\u003cdescription,Description\u003e\u003e text is dedented to the level of the first line, allowing for more flexible comment styles.\n\n=== Variables set/used\nGenerates a list of variables specified by \u003c\u003cenv,@env\u003e\u003e or \u003c\u003cset,@set\u003e\u003e, with sub-items for the function that set them.\nUseful when debugging, or reasoning about the whole program.\n\n.Example\n```markdown\n# Variables referenced.\n- `LOCATION`\n  - [`token:new`](#tokennew)\n- `CURSOR`\n  - [`location:cursor`](#locationcursor)\n  - [`lexer:advance`](#lexeradvance)\n- `TOKEN`\n  - [`parser:declaration`](#parserdeclaration)\n  - [`parser:typedef`](#parsertypedef)\n  - [`parser:type`](#parsertype)\n\n# Variables set.\n- `LOCATION`\n  - [`location:cursor`](#locationcursor)\n- `CHAR`\n  - [`lexer:advance`](#lexeradvance)\n- `TOKENS[]`\n  - [`token:new`](#tokennew)\n- `NODE`\n  - [`parser:declaration`](#parserdeclaration)\n  - [`parser:program`](#parserprogram)\n  - [`parser:typedef`](#parsertypedef)\n```\n\n\n== Flags\nAnnotation flags must occur...\n\n. attached to a function declaration (`@arg`, `@set`, `@env`, `@internal`)\n. attached to a variable declaration (`@type`)\n. attached to a function/section annotation (`@description`)\n. anywhere (`@section`)\n\n=== arg\nSpecifies an argument, with optional type and one-line description.\n\nTypes are indicated by a `:` prefix.\nAn anchor to the `Types` heading is created when the parameter type matches a \u003c\u003ctype,typedef\u003e\u003e.\n\n.Example\n```bash\n# @description\n#  Copies the properties from $1's location node to $2's. If no properties are\n#  specified, copies all of them. May only operate on TOKENs and NODEs.\n#\n# @arg   $1    :NODE    Source location-containing node\n# @arg   $2    :NODE    Destination location-containing node\nfunction location:copy {\n```\n\n.Output\n```markdown\n### location:copy()\n(*ln. 8, in input.sh*)\n\nCopies the properties from $1's location node to $2's. If no properties are\nspecified, copies all of them. May only operate on TOKENs and NODEs.\n\n#### args\n|name|type|desc|\n|:---|:---|:---|\n|`$1`|`NODE`|Source location-containing node|\n|`$2`|`NODE`|Destination location-containing node|\n```\n\n=== env\nIndicates the function references an environment/global variable.\n\n.Example\n```bash\n# @description\n#  Convenience function to create a location at the current cursor's position.\n#  Cleans up otherwise messy and repetitive code in the lexer.\n#\n# @set  LOCATION\n# @env  FILE_IDX\n# @env  CURSOR\n#\n# @noargs\nfunction location:cursor {\n```\n\n.Output\n```markdown\n# Variables referenced.\n- `CURSOR`\n  - [`location:cursor`](#locationcursor)\n- `FILE_IDX`\n  - [`location:cursor`](#locationcursor)\n\n# Functions.\n### location:cursor()\n(*ln. 11, in input.sh*)\n\nConvenience function to create a location at the current cursor's position.\nCleans up otherwise messy and repetitive code in the lexer.\n\n#### uses\n- `FILE_IDX`\n- `CURSOR`\n```\n\n=== set\nIndicates the function sets a global variable.\n\n.Example\n```bash\n# @description\n#  Throws error on circular imports, resolves relative paths to fully qualified\n#  path.\n#\n# @set   FILES[]\n# @set   FILE_IDX\n# @arg   $1    :str        Relative or absolute path to config file\n# @arg   $2    :LOCATION   [Optional] For error reporting import statements\nfunction utils:add_file {\n```\n\n.Output\n```markdown\n# Variables set.\n- `FILE_IDX`\n  - [`utils:add_file`](#utilsadd_file)\n- `FILES[]`\n  - [`utils:add_file`](#utilsadd_file)\n\n# Functions.\n### utils:add_file()\n(*ln. 10, in input.sh*)\n\nThrows error on circular imports, resolves relative paths to fully qualified\npath.\n\n#### args\n|name|type|desc|\n|:---|:---|:---|\n|`$1`|`str`|Relative or absolute path to config file|\n|`$2`|`LOCATION`|[Optional] For error reporting import statements|\n\n#### set\n- `FILES[]`\n- `FILE_IDX`\n```\n\n=== see\nCreates an anchor to another declared function.\n\n.Example\n```bash\n# @description\n#  Identifies and calls `utils:parse` on all import statements.\n#\n# @see   utils:parse\n# @arg   $1    :NODE     Root AST node for a file\nfunction imports:parse {\n```\n\n.Output\n```markdown\n### imports:parse()\n(*ln. 7, in input.sh*)\n\nIdentifies and calls `utils:parse` on all import statements.\n\n#### args\n|name|type|desc|\n|:---|:---|:---|\n|`$1`|`NODE`|Root AST node for a file|\n\n#### see\n- [`utils:parse`](#utilsparse)\n```\n\n=== internal\nIgnores this function definition in generated output.\nUseful for library functions you still wish to document.\n\n.Example\n```bash\n# @internal\n# @description\n#  Holdover until I wire up synchronization function. Called by parser:advance()\n#  to advance current global Token and nameref pointers.\n#\n# @see   parser:advance\n#\n# @env   TOKENS\n# @env   IDX\n# @set   TOKEN\n# @set   TOKEN_r\n# @noargs\nfunction parser:_advance {\n```\n\n=== description\nMay be attached to either a function definition or a sections's annotations to\nprovide more information.\n\nDescriptions may be multiline, and text is dedented to the position of the first\ntext-containing line after the `@description` flag.\n\nSee plenty of examples above.\n\n=== section\nCreates a higher level heading in the TOC, and the markdown body.\nUseful for indicating the following functions are all related.\n\n.Example\n```bash\n#===============================================================================\n# @section                           Utils\n# @description\n#  All of the utilities that tie together functionality from the lexer, parser,\n#  and compiler. Allows re-entering the parser for each included file, and\n#  concatenating (not literally, but in spirit) imported files.\n#-------------------------------------------------------------------------------\n```\n\n.Output\n```markdown\n# Contents.\n- [Utils](#utils)\n\n# Functions.\n## Utils\nAll of the utilities that tie together functionality from the lexer, parser,\nand compiler. Allows re-entering the parser for each included file, and\nconcatenating (not literally, but in spirit) imported files.\n```\n\nThe same dedentation rules apply as in the \u003c\u003cdescription\u003e\u003e.\n\n=== type\nIndicates the following variable declaration is a \"type\".\nAdds to a list in generated output, with reference to its line number.\nUseful if later annotating a function's \u003c\u003carg,arguments\u003e\u003e.\n\n.Example\n```bash\n# @type\ndeclare -g LOCATION=\n\n# @description\n#  Throws error on circular imports, resolves relative paths to fully qualified\n#  path.\n#\n# @set   FILES[]\n# @set   FILE_IDX\n# @arg   $1    :str        Relative or absolute path to config file\n# @arg   $2    :LOCATION   [Optional] For error reporting import statements\nfunction utils:add_file {\n```\n\n.Output\n```markdown\n# Types.\n|type|line|file|\n|:---|:---|:---|\n|`LOCATION`|`2`|*input.sh*|\n\n# Functions.\n### utils:add_file()\n(*ln. 13, in input.sh*)\n\nThrows error on circular imports, resolves relative paths to fully qualified\npath.\n\n#### args\n|name|type|desc|\n|:---|:---|:---|\n|`$1`|`str`|Relative or absolute path to config file|\n|`$2`|[`LOCATION`](#types)|[Optional] For error reporting import statements|\n\n#### set\n- `FILES[]`\n- `FILE_IDX`\n```\n\n\n== Known limitations\n=== Annotation placement\nComments with annotations must occur directly before function definitions.\nThey may not be placed inside the function's body, or after it.\n\n.This works.\n```bash\n# @arg $1 Adds one to this number\nfunction add_one { echo $(( $1 + 1 )) ;}\n```\n\n.These do not.\n```bash\n# @arg $1 Adds two to this number\n\nfunction add_two { echo $(( $1 + 2 )) ;}\n\n\nfunction add_three {\n   # @arg $1 Adds three to this number\n   echo $(( $1 + 3 ))\n}\n```\n\n=== Markdown anchors\nIt is currently possible to have an ambiguous anchor reference.\nI don't know how to make markdown anchors more specific.\n\n=== Links to typedefs\nSource files are parsed linearly.\nIf there is a defined \u003c\u003ctype,typedef\u003e\u003e for a function's \u003c\u003carg,argument\u003e\u003e type, an anchor is created.\n\nIf the typedef is declared *after* the function, there is no link.\nThere is no backtracking.\n\n.Example\nNo link will be created for the function's 1st parameter type, as it's declared\nafter the function itself.\n\n```bash\n# @arg   $1    :IP_ADDRESS\nfunction ping_ip_addr { :; }\n\n# @type\ndeclare -g IP_ADDRESS\n```\n\nOne will need to change the structure of their .sh files, or the order the files\nare sourced, so type declarations always precede their use.\n\nOr don't, and some links may not exist.\nIt's not a big deal.\n\n\n== Recognition\nObvious inspiration, and some outright function theft, from https://github.com/reconquest/shdoc[`shdoc`].\nI wanted to improve on a few edge cases, largely surrounding handling leading whitespace.\n\nUse `shdoc`, it is better and more robust than `awkdoc`.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcarlinigraphy%2Fawkdoc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcarlinigraphy%2Fawkdoc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcarlinigraphy%2Fawkdoc/lists"}