z.digitalclouds.dev | GitHub | Discussions | Localize

---

If there was a tool that parses scripts and extracts comments so it can be documented, collaborated, or used as a manual? If all can be automated so you can concentrate on the code while docs are made on the go? We got your back...

Contribute to make it better and get extra tools from our projects which are shared between contributors.
Code-newbies with the right attitude is always welcome.

---

Doxygen For Shell Scripts**

---

Example of our Z Shell code - https://z.digitalclouds.dev/docs/code

Parses Zsh and Bash scripts, outputs Asciidoc document with:

• list of functions, including auto-loading functions,
• call trees of functions and script body,
• comments for functions,
• features used for each function and for script body (features like: eval, read, vared, shopt, etc.),
• distinct marks for hooks registered with add-zsh-hook (Zsh),
• list of exported variables,
• list of used exported variables, together with the variable's origin (i.e. possibly another script).

Call trees support cross-file invocations, i.e. when a script calls a function defined in another file.

Written in Zshell language.

---

Installation

---

Default install path-prefix is /usr/local.

git clone https://github.com/z-shell/zsdoc
cd doc
make
sudo make install

For custom PREFIX variable in make invocation:

# 'sudo' may be required to install

make install PREFIX=~/opt/local
install -c -d ~/opt/local/share/zsdoc
install -c -d ~/opt/local/share/doc/zsdoc

cp build/zsd build/zsd-transform build/zsd-detect build/zsd-to-adoc ~/opt/local/bin
cp README.md NEWS LICENSE ~/opt/local/share/doc/zsdoc
cp zsd.config ~/opt/local/share/zsdoc

➜ cd ~/opt/local

➜ tree.
        ├── bin
        │   ├── zsd
        │   ├── zsd-detect
        │   ├── zsd-to-adoc
        │   └── zsd-transform
        │
        └── share
           ├── doc
           │   └── zsdoc
           │       ├── LICENSE
           │       ├── NEWS
           │       └── README.md
           │
           └── zsdoc
               └── zsd.config

Other available make variables are: INSTALL (to customize install command), BIN_DIR, SHARE_DIR, DOC_DIR.

---

Usage

---

zsd [-h/--help] [-v/--verbose] [-q/--quiet] [-n/--noansi] [--cignore <pattern>] {file1} [file2] ...

The files will be processed and their documentation will be generated in subdirectory `zsdoc' (with meta-data in subdirectory `data').

Options:
-h/--help      Usage information
-v/--verbose   More verbose operation-status output
-q/--quiet     No status messages
-n/--noansi    No colors in terminal output
--cignore      Specify which comment lines should be ignored
-f/--fpath     Paths are separated by: pointing to directories with functions
--synopsis     Text to be used in the SYNOPSIS section. Line break "... +\n", paragraph "...\n\n"
--scomm        Strip comment char "#" from function comments
--bash         Output is slightly tailored to Bash specifics (instead of Zsh specifics)

Example --cignore options:

--cignore '\#*FUNCTION:*{{{*'                 - ignore comments like # FUNCTION: usage {{{
--cignore '(\#*FUNCTION:*{{{*|\#*FUN:*{{{*)'  - also ignore comments like: # FUN: usage {{{

The file is parsed for synopsis block, which can be e.g.:
# synopsis {{{my synopsis, can be multi-line}}}

Another block that is parsed is commenting on environment variables. It consists of multiple
"VAR_NAME -> var description" lines and results in a table in the output AsciiDoc document.

---

Example:

---

# env-vars {{{
# PATH -> paths to executables
# MANPATH -> paths to manuals }}}

Change the default brace block-delimiters with --blocka, --blockb. Block body should be AsciiDoc.

---

Examples

---

example 1,
example 2
(also in PDF:
example 1,
example 2).

---

Few Rules

---

Few rules helping to use zsdoc in your project:

1. Write function comments before function. Empty lines between comment and function are allowed.
2. If you use special comments, e.g. vim (or emacs-origami) folds, you can ignore these lines with --cignore (see Usage).
3. If it's possible to avoid eval, then do that – zsdoc will analyze more code.
4. Currently, functions defined in functions are ignored, but this will change shortly.
5. I've greatly optimized the new Zsh version (5.4.2) for data processing – zsdoc parse long sources very fast starting from that Zsh version.
6. If you have multiple Zsh versions installed, then (for example) set zsh_control_bin="/usr/local/bin/zsh-5.4.2" in /usr/local/share/zsdoc/zsd.config.
7. Be aware that to convert a group of scripts, you simply need zsd file1.zsh file2.zsh ... – cross-file function invocations will work automatically, and multiple *.adoc files will be created.
8. Create Makefile with doc target, that does rm -rf zsdoc/data; zsd -v file1.zsh .... Documentation will land in zsdoc directory.
9. Directory zsdoc/data holds meta-data used to create asciidoc documents (*.adoc files). You can remove it or analyze it yourself.
10. Obtain PDFs with Asciidoctor tool via: asciidoctor -b pdf -r asciidoctor-pdf file1.zsh.adoc. Install Asciidoctor with: gem install asciidoctor-pdf --pre. (Check out ZI's Makefile.)
11. HTML: asciidoctor script.adoc.
12. Obtain manual pages with Asciidoc package via: a2x -L --doctype manpage --format manpage file1.zsh.adoc (asciidoc is a common package; its a2x command is little slow).
13. Github supports Asciidoc documents and renders them automatically.