Re: Doxygen for shell scripts

["Nikolay Aleksandrovich Pavlov (ZyX)" <kp-pav@yandex.ru>]

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