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

[Francesco]

Hi Fabrice,
Thanks for the pointer.
Pandoc however seems to be able to convert only _to_ Asciidoc, not _from_
Asciidoc (by looking at https://pandoc.org/).
Anyway, thanks to some regex I managed to upgrade the format of the
Asciidoc documentation from the legacy format to the "modern/current"
Asciidoc format.

I have updated the PR at https://github.com/zeromq/libzmq/pull/4607
Documentation rendered as Github Pages in my own fork:
https://f18m.github.io/libzmq/

Any comment is welcome

Thanks,
Francesco


Il giorno mar 24 ott 2023 alle ore 09:20 Fabrice Bacchella <
fabrice.bacchella at orange.fr> ha scritto:

> 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> 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.viren at gmail.com> ha scritto:
>>
>>> On Fri, Oct 20, 2023 at 12:03 PM Francesco <francesco.montorsi at 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 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
>
>
> _______________________________________________
> 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/042ad6d4/attachment.htm>