Skip to content

z-shell/zsdoc

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

27 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Logo

Doxygen For Shell Scripts

Introduction

Parses Zsh and Bash scripts, outputs Asciidoc document with:

  • list of functions, including autoload functions,
  • call trees of functions and script body,
  • comments for functions,
  • features used for each function and 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 and 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 other files.

They are written in Zshell language.

Installation

The default install path-prefix is /usr/local.

git clone https://github.com/z-shell/zsdoc
cd zsdoc
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 the 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 slightly tailored to Bash specifics (instead of Zsh specifics)

Example --cignore options:

# Ignore comments like: # FUNCTION: usage {{{
--cignore  '\#[[:blank:]]FUNCTION:[[:blank:]]*[[:blank:]]{{{*'
# Ignore comments like: # FUN: usage {{{
--cignore '(\#[[:blank:]]FUN(C|CTION|):[[:blank:]]*[[:blank:]]{{{*|[[:blank:]]\#[[:blank:]]}}}*)'
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-delimeters with --blocka, and --blockb. The block body should be AsciiDoc.

Examples

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

Few Rules

Here are a few rules helping to use zsdoc in your project:

  1. Write function comments before the function. Empty lines between comments and functions 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 parses 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 the 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 a little slow).
  13. Github supports Asciidoc documents and renders them automatically.