{"id":13473506,"url":"https://github.com/reconquest/shdoc","last_synced_at":"2026-01-27T02:08:12.685Z","repository":{"id":8421157,"uuid":"58310662","full_name":"reconquest/shdoc","owner":"reconquest","description":"Documentation generator for shell scripts (bash, sh, zsh). Javadoc for shell scripts.","archived":false,"fork":false,"pushed_at":"2023-10-11T08:33:26.000Z","size":102,"stargazers_count":312,"open_issues_count":24,"forks_count":64,"subscribers_count":9,"default_branch":"master","last_synced_at":"2025-02-27T07:14:01.106Z","etag":null,"topics":[],"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/reconquest.png","metadata":{"files":{"readme":"README.md","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}},"created_at":"2016-05-08T12:18:31.000Z","updated_at":"2025-02-26T13:18:15.000Z","dependencies_parsed_at":"2024-01-16T15:40:42.191Z","dependency_job_id":"241bcf56-72d0-46fb-9c2c-b9e7004b261f","html_url":"https://github.com/reconquest/shdoc","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/reconquest/shdoc","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/reconquest%2Fshdoc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/reconquest%2Fshdoc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/reconquest%2Fshdoc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/reconquest%2Fshdoc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/reconquest","download_url":"https://codeload.github.com/reconquest/shdoc/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/reconquest%2Fshdoc/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28796962,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-27T01:07:07.743Z","status":"online","status_checked_at":"2026-01-27T02:00:07.755Z","response_time":168,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":[],"created_at":"2024-07-31T16:01:04.270Z","updated_at":"2026-01-27T02:08:12.669Z","avatar_url":"https://github.com/reconquest.png","language":"Awk","readme":"# shdoc\n\nshdoc is a documentation generator for bash/zsh/sh for generating API documentation in Markdown from\nshell scripts source.\n\nshdoc parses [annotations](#features) in the beginning of a given file and alongside function\ndefinitions, and creates a markdown file with ready to use documentation.\n\n## Index\n\n* [Example](#example)\n* [Annotations](#annotations)\n* [Usage](#usage)\n* [Installation](#installation)\n* [More examples](#examples)\n* [License](#license)\n\n## Example\n\n\u003ctable border=\"0\"\u003e\n \u003ctr\u003e\n    \u003ctd style=\"vertical-align: top\"\u003e\n\nGenerate documentation with the following command:\n~~~bash\n$ shdoc \u003c lib.sh \u003e doc.md\n~~~\n\n_Source_ [examples/readme-example.sh](examples/readme-example.sh)\u003cbr /\u003e\n_Output_: [examples/readme-example.md](examples/readme-example.md)\u003cbr/\u003e\u003cbr/\u003e\n~~~bash\n#!/bin/bash\n# @file libexample\n# @brief A library that solves some common problems.\n# @description\n#     The project solves lots of problems:\n#      * a\n#      * b\n#      * c\n#      * etc\n\n# @description My super function.\n# Not thread-safe.\n#\n# @example\n#    echo \"test: $(say-hello World)\"\n#\n#\n# @option -h | --help Display help.\n# @option -v\u003cvalue\u003e | --value=\u003cvalue\u003e Set a value.\n#\n# @arg $1 string A value to print\n#\n# @stdout Output 'Hello $1'.\n#   It hopes you say Hello back.\n# @stderr Output 'Oups !' on error.\n#   It did it again.\n#\n# @exitcode 0 If successful.\n# @exitcode 1 If an empty string passed.\n#\n# @see validate()\n# @see [shdoc](https://github.com/reconquest/shdoc).\nsay-hello() {\n    if [[ ! \"$1\" ]]; then\n        echo \"Oups !\" \u003e\u00262\n        return 1;\n    fi\n\n    echo \"Hello $1\"\n}\n~~~\n\n\n\u003c/td\u003e\n\u003ctd\u003e\n\n~~~markdown\n# libexample\n\nA library that solves some common problems.\n\n## Overview\n\nThe project solves lots of problems:\n* a\n* b\n* c\n* etc\n\n## Index\n\n* [say-hello](#say-hello)\n\n### say-hello\n\nMy super function.\nNot thread-safe.\n\n#### Example\n\n```bash\necho \"test: $(say-hello World)\"\n```\n\n#### Options\n\n* **-h** | **--help**\n\n  Display help.\n\n* **-v\\\u003cvalue\\\u003e** | **--value=\\\u003cvalue\\\u003e**\n\n  Set a value.\n\n#### Arguments\n\n* **$1** (string): A value to print\n\n#### Exit codes\n\n* **0**: If successful.\n* **1**: If an empty string passed.\n\n#### Output on stdout\n\n* Output 'Hello $1'.\n  It hopes you say Hello back.\n\n#### Output on stderr\n\n* Output 'Oups !' on error.\n  It did it again.\n\n#### See also\n\n* [validate()](#validate)\n* [shdoc](https://github.com/reconquest/shdoc).\n\n~~~\n\n\u003c/td\u003e\n\u003c/tr\u003e\u003c/table\u003e\n\n\n## Features\n\n### `@name`\n\nA name of the project, used as a title of the doc. Can be specified once in the beginning of the\nfile.\n\n**Example**\n\n```bash\n#!/bin/bash\n# @name MyLibrary\n```\n\n### `@file`\n\nIdentical to [@name](#name).\n\n### `@brief`\n\nA brief line about the project. Can be specified once in the beginning of the file.\u003cbr\u003e\n\n**Example**\n```bash\n#!/bin/bash\n# @brief A library to solve a few problems.\n```\n\n### `@description`\n\nA multiline description of the project/section/function.\n* Can be specified once for the whole file in the beginning of the file.\n* Can be specified once for a section of the file. See [@section](#section).\n* Can be specified once for on top of a function definition.\n\n**Example**\n```bash\n#!/bin/bash\n# @description A long description of the library.\n# Second line of the project description.\n\n# @description My super function.\n# Second line of my super function description.\nfunction super() {\n    ...\n}\n```\n\n### `@section`\n\nThe name of a section of the file. Can be used to group functions.\n\n**Example**\n```bash\n# @section My utilities functions\n# @description The following functions can be used to solve problems.\n```\n\n### `@example`\n\nA multiline example of the function usage. Can be specified only alongside the function definition.\n\n**Example**\n```bash\n# @example\n#    echo \"test: $(say-hello World)\"\nsay-hello() {\n    ...\n}\n```\n\n### `@option`\n\nA description of an option expected to be passed while calling the function.\nCan be specified multiple times to describe any number of arguments.\nIf an option argument is expected, it must be specified between `\u003c` and `\u003e`\n\n**Example**\n\n```bash\n# @description Says hi to a given person.\n# @option -h A short option.\n# @arg --value=\u003cvalue\u003e A long option with argument.\n# @arg -v\u003cvalue\u003e | --value \u003cvalue\u003e A long option with short option alternative.\nsay-hello() {\n    ...\n}\n```\n\n### `@arg`\n\nA description of an argument expected to be passed while calling the function.\nCan be specified multiple times to describe any number of arguments.\n\n**Example**\n\n```bash\n# @description Says hi to a given person.\n# @arg $1 string A person's name.\n# @arg $2 string Message priority.\nsay-hello() {\n    ...\n}\n```\n\n### `@noargs`\n\nA note that the function does not expect any arguments to be passed.\n\n**Example**\n\n```bash\n# @description Says 'hello world'.\n# @noargs\nsay-hello-world() {\n    ...\n}\n```\n\n### `@set`\n\nA description of a global variable that is set while calling the function.\nCan be specified multiple times to describe any number of variables\n\n**Example**\n\n```bash\n# @description Sets hello to the variable REPLY\n# @set REPLY string Greeting message.\nset-hello() {\n    ...\n}\n```\n\n### `@exitcode`\n\nDescribes an expected exitcode of the function.\nCan be specified multiple times to describe all possible exitcodes and their conditions.\n\n**Example**\n\n```bash\n# @description Says 'hello world'.\n# @exitcode 0 If successful.\n# @exitcode 1 If world is gone.\nsay-hello-world() {\n    ...\n}\n```\n\n### `@stdin`\n\nThe expected input to the function call from `stdin` (usually the terminal or command line)\n\n**Example**\n\n```bash\n# @description Asks name.\n# @stdin The users name from the terminal/command line.\nsay-hello-world() {\n    ...\n}\n```\n\n### `@stdout`\n\nAn expected output of the function call.\n\n**Example**\n\n```bash\n# @description Says 'hello world'.\n# @stdout A path to a temporary file with the message.\nsay-hello-world() {\n    ...\n}\n```\n\n### `@stderr`\n\nAn expected output of the function call on `/dev/stderr`.\n\n**Example**\n\n```bash\n# @description Says 'hello world'.\n# @stderr A error message when world is not available.\nsay-hello-world() {\n    ...\n}\n```\n\n### `@see`\n\nCreate a link on the given function in the \"See Also\" section.\n\n**Example**\n\n```bash\n# @see say-hello\n# @see text with [markdown link](./other-file#other-function)\nsay-hello-world() {\n    ...\n}\n```\n\n### `@internal`\n\nWhen you want to skip documentation generation for a particular function, you can specify this\n`@internal` tag.\nIt allows you to have the same style of doc comments across the script and keep internal\nfunctions hidden from users.\n\n**Example**\n\n```bash\n# @internal\nshow-msg() {\n    ...\n}\n```\n\n## Usage\n\nshdoc has no args and expects a shell script with comments on stdin and will produce markdown as stdout.\n\n```bash\n$ shdoc \u003c your-shell-script.sh \u003e doc.md\n```\n\n## Installation\n\n### Arch Linux\n\nArch Linux users can install shdoc using package in AUR: [shdoc-git](https://aur.archlinux.org/packages/shdoc-git)\n\n### Using Git\n\nNOTE: shdoc requires gawk: `apt-get install gawk`\n\n```bash\ngit clone --recursive https://github.com/reconquest/shdoc\ncd shdoc\nsudo make install\n```\n\n### Others\n\nUnfortunately, there are no packages of shdoc for other distros, but we're looking for contributions.\n\n## Examples\n\nSee example documentation on:\n\n* [tests.sh](https://github.com/reconquest/tests.sh/blob/master/REFERENCE.md)\n* [coproc.bash](https://github.com/reconquest/coproc.bash/blob/master/REFERENCE.md)\n\n# LICENSE\n\nMIT\n","funding_links":[],"categories":["Awk","others","Applications"],"sub_categories":["Documentation Generation"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Freconquest%2Fshdoc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Freconquest%2Fshdoc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Freconquest%2Fshdoc/lists"}