[zeromq-dev] ZeroMQ docs

[Francesco]

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
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.zeromq.org/pipermail/zeromq-dev/attachments/20231023/5de19b6a/attachment.htm>