Hi all, Here's an update on my attempt to refresh the doc system for libzmq API.
*Current status:* libzmq is built around the "ancient" python Asciidoc tool. That tool is unmaintained for several years and has been replaced by the Asciidoctor tool (see https://docs.asciidoctor.org/asciidoctor/latest/migrate/asciidoc-py/). Note that the original tool used for interpreting the .txt files was named "asciidoc" just like the language markup contained in the .txt files itself. To avoid confusion, that tool is now referred to as "asciidoc-py". The tool asciidoc-py is the one unmaintained. The language Asciidoc itself instead is still maintained and developed, but Asciidoctor is the only updated tool to process Asciidoc documents. The manpages are built today in libzmq through this chain: .txt --[asciidoc]--> .xml docbook --[xmlto]--> .3 or .7 manpages where the [] indicate the tool used for the conversion. Also the utility "xmlto" seems quite unmaintained. Finally the wikidot website http://api.zeromq.org/ is built from some scripts located in the "ztools" repo that basically leverages the ability of that wiki to produce a listing of all wiki pages uploaded by group; the group used is the ZMQ API version. This makes it possible to document multiple versions of the libzmq API in the same website/wiki. However wikidot itself seems unmaintained as well. *Where I got so far:* I managed to convert to obtain usable and nicely-formatted HTML docs running Asciidoctor on libzmq docs, after some mass-replacement passes to fix some syntax issues. Asciidoctor is still processing all libzmq docs using the so-called "compatibility mode". In my libzmq fork I enabled Github pages and I got them deployed on every checkin of my branch. Documentation rendered as Github Pages in my own fork: https://f18m.github.io/libzmq/ PR: https://github.com/zeromq/libzmq/pull/4607 *Next steps:* a) I'm fighting a little bit with Asciidoctor to get the right rendering also for manpages. b) Some smart mass-replace is still needed to convert from the deprecated Asciidoc format to the "modern" Asciidoc (see https://docs.asciidoctor.org/asciidoctor/latest/migrate/asciidoc-py/#updated-and-deprecated-asciidoc-syntax ) c) The Github pages approach is able to deploy only the documentation for the latest "master" branch. Maintaining documentation for the multiple API versions is probably best achieved using the more popular readthedocs.io. As pointed out already in this email thread, readthedocs.io is mostly designed around Sphinx and MkDocs but most recent versions are flexible enough to accomodate also Asciidoc documentation. I think eadthedocs.io is the best solution to store different versions of libzmq API. Please let me know if you have any comments. In my opinion to simplify the PR review, after step a) it's best to do a first merge, and then carry out points b) and c) in 2 more separate PRs. What do you think? Thanks, Il giorno ven 20 ott 2023 alle ore 18:19 Brett Viren <[email protected]> ha scritto: > On Fri, Oct 20, 2023 at 12:03 PM Francesco <[email protected]> > wrote: > > > > Maybe an even simpler solution is to activate the Github "Pages" support > in libzmq.org and link it with a github action that just uses the > Asciidoctor generator to convert all of doc/*.txt into static HTML. > > > > What do you think about this? > > This sounds like a very good idea to me. And, it's even easier as the > existing libzmq build already produces the HTML. > > On could prototype some additional build action that populate the > special gh-pages by committing these generated HTML files. This can > be tested using a personal fork of libzmq to make your own > https://<name>.github.io/libzmq/. When that works, a PR to libzmq > would be needed. Bonus if some .github/ CI bits could automate this. > And, someone with GitHub permissions would need to go into libzmq's > repo settings to turn on the publish setting. > > -Brett. > _______________________________________________ > zeromq-dev mailing list > [email protected] > https://lists.zeromq.org/mailman/listinfo/zeromq-dev >
_______________________________________________ zeromq-dev mailing list [email protected] https://lists.zeromq.org/mailman/listinfo/zeromq-dev
