[zeromq-dev] *** SPAM *** Re: ZeroMQ docs

[Fabrice Bacchella]

Did you try pandoc ?

> Le 23 oct. 2023 à 23:16, Francesco <francesco.montorsi at gmail.com> a écrit :
> 
> 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.montorsi at gmail.com <mailto:francesco.montorsi at 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 <http://readthedocs.io/>. As pointed out already in this email thread, readthedocs.io <http://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 <http://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.viren at gmail.com <mailto:brett.viren at gmail.com>> ha scritto:
>>> On Fri, Oct 20, 2023 at 12:03 PM Francesco <francesco.montorsi at gmail.com <mailto:francesco.montorsi at gmail.com>> wrote:
>>> >
>>> > Maybe an even simpler solution is to activate the Github "Pages" support in libzmq.org <http://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/ <http://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 at lists.zeromq.org <mailto:zeromq-dev at lists.zeromq.org>
>>> https://lists.zeromq.org/mailman/listinfo/zeromq-dev
> _______________________________________________
> zeromq-dev mailing list
> zeromq-dev at lists.zeromq.org
> https://lists.zeromq.org/mailman/listinfo/zeromq-dev

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.zeromq.org/pipermail/zeromq-dev/attachments/20231024/357e3df9/attachment.htm>