API doc via zshelldoc?
rocky opened this issue · 7 comments
See https://github.com/zdharma/hacking-private/tree/master/zshdb
Some comments on that format:
- Commands seem to be tagged shell commands and as such get an added
(1), e.g. action.sh(1) - The synopsis should be taken from the doc string that is already in the file. For example instead of "Documentation automatically generated with `zshelldoc'" the synopsis for action.sh should be:
action linespec command
Run command when linespec is hit
Use "A" to remove all actions and "L" to get a list of the actions in
effect.'
- The collected documentation should appear in its own folder and not in the top-level directory
The (1) and SYNOPSIS are because the asciidoc-package command a2x can convert to manpage if beginning of document is like that. Not sure if asciidoctor converter has the same requirements, will check tomorrow.
So action is a kind of a sentinel that waits for linespec to match, i.e. waits for a line in source that is stepped over and matches linespec? I plan to add some special javadoc-like or doxygen-like markers so that e.g. file can be commented on, not only function, this looks like a good moment.
The documentation is put in separate directory zsdoc. The command is just: zsd *.sh ran in lib/, I now spotted a problem that this cannot be zsd lib/*.sh, I will fix this tomorrow.
BTW. Zshelldoc should also work on Bash scripts.
BTW. Zshelldoc should also work on Bash scripts.
If you lead the way on this in zshdb, I'll follow and apply it to bashdb. Thanks.
As for the synopsis, zsd now supports a special block
# synopsis {{{my synopsis, can be multi-line}}}
I'll take a look at the general condition of the documentation obtained till tomorrow.
Can we get everything on readthedocs? e.g. https://zshdb.readthedocs.io/en/latest/ ?
I think that yes, but with a cost – to convert the AsciiDoc to Markdown. I could either add option to ZshellDoc to generate Markdown – from which my project would also benefit – or prepare a script that would do the conversion with regular expressions. I'll think about which option to take.
I've regenerated the documentation with current ZSD, it is at: https://github.com/zdharma/hacking-private/tree/master/zshdb. I think that it's in overall good shape and the lecture does help to grasp how Zshdb works. If only a few of the crucial functions be commented on with a few sentences, this would be even easier.
For readthedocs use, although they claim to support markdown, I've never been able to get it to work as well as ReStructuredText. Sphynx documentation is here
In the past I've gone down the route where someone maintained docs externally using their own system.
From my side the results have never been as up to date as when this is automated and changes automatically with the documentation.
I am all for adding additional documentation in the library code to aid understanding, but it has to done incrementally and automatically. It's taken me several years to get just the commands up to date this much, and still there is more to be desired. The recent set of changes to the RsT and readthedocs alas is still not complete, but I put effort more effort into only to the extent that I have time, and the project popularity warrants it.
To that point, the ratings on this project fall below two other projects.
I've tried the markdown on RTD and it doesn't look the same as as good as rST: https://zplugin.readthedocs.io/. The theme is different and I think that it's subpar to the one used when using Spynx. I'm getting ready to implement the rST into Zshelldoc.