Doxygen for shell scripts

Doxygen for shell scripts

[Sebastian Gniazdowski]

Hello
I've written a documentation generator for shell scripts. Example outputs:

https://github.com/zdharma/zshelldoc/tree/master/examples

It is based on (z) flag, works very robust. Supported are things like autoload functions and calls between scripts. I think the most power comes from call trees and comment extraction – this allows to analyze the code – but I plan to add some more things, like detection of usage of Zle, eval, add-zsh-hook, etc.

--  
Sebastian Gniazdowski
psprint /at/ zdharma.org

Re: Doxygen for shell scripts

[Nikolay Aleksandrovich Pavlov (ZyX)]

10.09.2017, 10:16, "Sebastian Gniazdowski" <psprint@zdharma.org>:
> Hello
> I've written a documentation generator for shell scripts. Example outputs:
>
> https://github.com/zdharma/zshelldoc/tree/master/examples
>
> It is based on (z) flag, works very robust. Supported are things like autoload functions and calls between scripts. I think the most power comes from call trees and comment extraction – this allows to analyze the code – but I plan to add some more things, like detection of usage of Zle, eval, add-zsh-hook, etc.
>
> --
> Sebastian Gniazdowski
> psprint /at/ zdharma.org

Why not a sphinx plugin? It is most logical: you need to teach it how to extract documentation comments and whatever those “more things” you want and it takes the job of yielding nicely formatted documentation in many different formats (one of which includes man pages), provides ability to host the generated documentation on readthedocs (but you still can have static pages on github.io or anwhere else if you want), TOC (table of contents) generating, cross-referencing, code highlighting (via pygments), searching (by default: local javascript-based search, not as good as google or properly configured another sphinx, but usable).

Re: Doxygen for shell scripts

[Sebastian Gniazdowski]

On 10.09.2017 at 11:43:54, Nikolay Aleksandrovich Pavlov (ZyX) (kp-pav@yandex.ru) wrote:
> Why not a sphinx plugin? It is most logical: you need to teach it how to extract documentation  
> comments and whatever those “more things” you want and it takes the job of yielding nicely  
> formatted documentation in many different formats (one of which includes man pages),  

There's a problem with this route – zsd uses (z) flag, which apparently exposes the original parser used by Zsh. So it's easy to parse and this is robust, because the parser has enough attention from developers. With Sphinx I would have to write own parser in Python. This is for sure doable, especially because shell syntax has multiple simplifications (like: require space after [[ in condition [[ ... ]]), but AFAIK nobody has done this yet, so no resources, examples, etc. I think many people had this idea, to write doxygen-like tool or something similar for shell scripts, but everybody stepped down because of the parser effort and doubts if shell scripts are sophisticated enough to address them. Zsh plugins are often sophisticated so maybe ZSD will be used, and (z) flag solves the effort-problem, even for Bash – just tried to run ZSD on an old 550-line Bash script with 9 functions (it implements youtube-dl queue, for slow networks), and it worked.

--  
Sebastian Gniazdowski
psprint /at/ zdharma.org

Re: Doxygen for shell scripts

[Nikolay Aleksandrovich Pavlov (ZyX)]

11.09.2017, 15:15, "Sebastian Gniazdowski" <psprint@zdharma.org>:
> On 10.09.2017 at 11:43:54, Nikolay Aleksandrovich Pavlov (ZyX) (kp-pav@yandex.ru) wrote:
>>  Why not a sphinx plugin? It is most logical: you need to teach it how to extract documentation
>>  comments and whatever those “more things” you want and it takes the job of yielding nicely
>>  formatted documentation in many different formats (one of which includes man pages),
>
> There's a problem with this route – zsd uses (z) flag, which apparently exposes the original parser used by Zsh. So it's easy to parse and this is robust, because the parser has enough attention from developers. With Sphinx I would have to write own parser in Python.

No, you don’t, there is no requirement to not call external applications during documentation build process. You may have to invoke zsh which will do some parsing and serialize the result for Python which will do most of the job for creating documentation.

> This is for sure doable, especially because shell syntax has multiple simplifications (like: require space after [[ in condition [[ ... ]]), but AFAIK nobody has done this yet, so no resources, examples, etc. I think many people had this idea, to write doxygen-like tool or something similar for shell scripts, but everybody stepped down because of the parser effort and doubts if shell scripts are sophisticated enough to address them. Zsh plugins are often sophisticated so maybe ZSD will be used, and (z) flag solves the effort-problem, even for Bash – just tried to run ZSD on an old 550-line Bash script with 9 functions (it implements youtube-dl queue, for slow networks), and it worked.
>
> --
> Sebastian Gniazdowski
> psprint /at/ zdharma.org