{"id":13536942,"url":"https://github.com/zdharma-continuum/zshelldoc","last_synced_at":"2025-04-10T00:35:54.289Z","repository":{"id":103427574,"uuid":"425466405","full_name":"zdharma-continuum/zshelldoc","owner":"zdharma-continuum","description":null,"archived":false,"fork":false,"pushed_at":"2023-11-20T08:40:18.000Z","size":309,"stargazers_count":19,"open_issues_count":0,"forks_count":2,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-03-24T02:21:49.948Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/zdharma-continuum.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2021-11-07T09:56:02.000Z","updated_at":"2025-02-26T08:49:30.000Z","dependencies_parsed_at":"2023-11-20T09:28:14.928Z","dependency_job_id":"18a27d23-81fa-43ed-aec1-d71e7f937d8b","html_url":"https://github.com/zdharma-continuum/zshelldoc","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zdharma-continuum%2Fzshelldoc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zdharma-continuum%2Fzshelldoc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zdharma-continuum%2Fzshelldoc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zdharma-continuum%2Fzshelldoc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zdharma-continuum","download_url":"https://codeload.github.com/zdharma-continuum/zshelldoc/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247749955,"owners_count":20989714,"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":[],"created_at":"2024-08-01T09:00:52.293Z","updated_at":"2025-04-10T00:35:54.271Z","avatar_url":"https://github.com/zdharma-continuum.png","language":"Shell","readme":"# Zshelldoc - Doxygen For Shell Scripts\n\nParse `Zsh` \u0026 `Bash` scripts and outputs `Asciidoc` document with:\n\n- list of functions (including autoload functions)\n- call trees of functions and script body\n- comments for functions\n- features used for each function and script body (features like: `eval`, `read`, `vared`, `shopt`, etc.)\n- distinct marks for hooks registered with `add-zsh-hook` (Zsh)\n- list of exported variables\n- list of used exported variables and the variable's origin (i.e., possibly another script)\n\nCall trees support cross-file invocations, i.e., when a script calls a function defined in another file.\n\nZshelldoc is written in `Zshell` language.\n\n![image](https://raw.githubusercontent.com/zdharma-continuum/zshelldoc/images/env_feat_demo.png)\n\n## Usage\n\n```\nUsage: zsd [-hnqv] [--cignore pattern] [--noansi] [--verbose] file [...]\n\n   The files will be processed and their documentation will be generated\n   in subdirectory zsdoc (with meta-data in subdirectory data).\n   Supported are Bash and Zsh scripts\n\nOptions:\n  -f, --fpath      Paths separated by pointing to directories with functions\n  -h, --help       Usage information\n  -n, --noansi     No colors in terminal output\n  -q, --quiet      No status messages\n  -v, --verbose    More verbose operation-status output\n      --bash       Output slightly tailored to Bash specifics (instead of Zsh specifics)\n      --blocka     String used as block-begin, default: {{{\n      --blockb     String used as block-end, default: }}}\n      --cignore    Specify which comment lines should be ignored\n      --scomm      Strip comment char # from function comments\n      --synopsis   Text to be used in SYNOPSIS section. Line break \\\"... +\\n\\\", paragraph \\\"...\\n\\n\\\"\n\nExample --cignore values:\n  --cignore (\\\\#*FUNCTION:*{{{*|\\\\#*FUN:*{{{*)  Ignore comments like:# FUN: usage {{{\n  --cignore \\\\#*FUNCTION:*{{{*                   Ignore comments like: # FUNCTION: usage {{{\n\nSynopsis block:\n   # synopsis {{{my synopsis, can be multi-line}}}\n\nEnvironment variables block\n   There can be multiple such blocks their content will be merged. The block can\n   consist of multiple variables using the VAR_NAME -\u003e var-description format.\n   It will be rendered as a table in the output AsciiDoc document.\n\n   Example:\n   # env-vars {{{\n   # PATH -\u003e paths to executables\n   # MANPATH -\u003e paths to manuals\n   # }}}\n\nChange the default brace block-delimeters with --blocka, --blockb. Block body should be AsciiDoc\n```\n\n## Install\n\nClone and issue `make \u0026\u0026 make install`. Default install path-prefix is `/usr/local`, you can change it by setting\n`PREFIX` variable in `make` invocation:\n\n```sh\nmake install PREFIX=~/opt/local\ninstall -c -d ~/opt/local/share/zshelldoc\ninstall -c -d ~/opt/local/share/doc/zshelldoc\ncp build/zsd build/zsd-transform build/zsd-detect build/zsd-to-adoc ~/opt/local/bin\ncp README.md NEWS LICENSE ~/opt/local/share/doc/zshelldoc\ncp zsd.config ~/opt/local/share/zshelldoc\n```\n\n```sh\ntree ~/opt\n/Users/sgniazdowski/opt\n└── local\n├── bin\n│   ├── zsd\n│   ├── zsd-detect\n│   ├── zsd-to-adoc\n│   └── zsd-transform\n└── share\n├── doc\n│   └── zshelldoc\n│   ├── LICENSE\n│   ├── NEWS\n│   └── README.md\n└── zshelldoc\n└── zsd.config\n```\n\nOther available `make` variables are: `INSTALL` (to customize install command), `BIN_DIR`, `SHARE_DIR`, and `DOC_DIR`.\n\n## Examples\n\n`Zshelldoc` highly motivates to document code, and `zinit` gained from this. Also, `zinit` documentation demonstrates\nrich cross-file invocations.\n[Check out zinit's code documentation](https://github.com/zdharma-continuum/zinit/tree/master/zsdoc).\n\n- [zsh-syntax-highlighting](https://github.com/zdharma-continuum/zshelldoc/blob/master/examples/zsh-syntax-highlighting.zsh.adoc),\n- [zsh-syntax-highlighting PDF](https://raw.githubusercontent.com/zdharma-continuum/zshelldoc/master/examples/zsh-syntax-highlighting.zsh.pdf)\n- [zsh-autosuggestions](https://github.com/zdharma-continuum/zshelldoc/blob/master/examples/zsh-autosuggestions.zsh.adoc)\n- [zsh-autosuggestions PDF](https://raw.githubusercontent.com/zdharma-continuum/zshelldoc/master/examples/zsh-autosuggestions.zsh.pdf)\n\n## How to use\n\nHere are a few rules helping to use `Zshelldoc` in your project:\n\n1. Write function comments before the function. Empty lines between comments and functions are allowed.\n\n1. If you use special comments, e.g., `vim` (or `emacs-origami`) **folds**, you can ignore these lines with `--cignore`\n   (see [Usage](https://github.com/zdharma/zshelldoc#usage)).\n\n1. If it's possible to avoid `eval`, then do that – `Zshelldoc` will analyze more code.\n\n1. Currently, functions defined in functions are ignored, but this will change shortly.\n\n1. I've greatly optimized the new `Zsh` version (`5.4.2`) for data processing – `Zshelldoc` parses long sources very\n   fast starting from that `Zsh` version.\n\n1. If you have multiple `Zsh` versions installed, then (for example) set `zsh_control_bin=\"/usr/local/bin/zsh-5.4.2\"` in\n   `/usr/local/share/zshelldoc/zsd.config`.\n\n1. Be aware that to convert a group of scripts, you simply need `zsd file1.zsh file2.zsh ...` – cross-file function\n   invocations will work automatically, creating multiple `*.adoc` files.\n\n1. Create `Makefile` with `doc` target, that does `rm -rf zsdoc/data; zsd -v file1.zsh ...`. Documentation will land in\n   `zsdoc` directory.\n\n1. Directory `zsdoc/data` holds meta-data used to create `asciidoc` documents (`*.adoc` files). You can remove it or\n   analyze it yourself.\n\n1. To install `Asciidoctor`, run:\n\n   ```sh\n   gem install asciidoctor-pdf --pre\n   ```\n\n1. To generate **PDFs** via [Asciidoctor](http://asciidoctor.org/), run:\n\n   ```sh\n   asciidoctor -b pdf -r asciidoctor-pdf file1.zsh.adoc\n   ```\n\n   If you have trouble, see [zinit's Makefile](https://github.com/zdharma-continuum/zinit/blob/master/zsdoc/Makefile).\n\n1. HTML: `asciidoctor script.adoc`.\n\n1. Obtain manual pages with the `Asciidoc` package via: `a2x -L --doctype manpage --format manpage file1.zsh.adoc`\n   (`asciidoc` is a typical package; its `a2x` command is a little slow).\n\n1. Github supports `Asciidoc` documents and renders them automatically.\n","funding_links":[],"categories":["Other Resources","Shell","Applications"],"sub_categories":["ZSH Tools","Documentation Generation"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzdharma-continuum%2Fzshelldoc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzdharma-continuum%2Fzshelldoc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzdharma-continuum%2Fzshelldoc/lists"}