Update: apparently the point a) is blocked by point b). In more details: the Asciidoc modern syntax to get a cross-reference correctly rendered in both manpages and HTMLs is:
xref:name_of_doc.adoc[name_of_doc] This will produce a valid link to "name_of_doc.html" for HTML output and a simple "name_of_doc" span of text for manpage output. This is the fix mentioned in step a). However this syntax is accepted only when Asciidoctor is NOT running in legacy/deprecated mode. To avoid that, I first need step b). Shall I put steps a) and b) together in my same WIP PR ? It will be harder to review it... thanks Il giorno lun 23 ott 2023 alle ore 22:43 Francesco < francesco.monto...@gmail.com> ha scritto: > 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 < > brett.vi...@gmail.com> ha scritto: > >> On Fri, Oct 20, 2023 at 12:03 PM Francesco <francesco.monto...@gmail.com> >> 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 >> zeromq-dev@lists.zeromq.org >> https://lists.zeromq.org/mailman/listinfo/zeromq-dev >> >
_______________________________________________ zeromq-dev mailing list zeromq-dev@lists.zeromq.org https://lists.zeromq.org/mailman/listinfo/zeromq-dev
