[zeromq-dev] ZeroMQ docs

Francesco francesco.montorsi at gmail.com
Sat Nov 4 23:30:52 CET 2023


hi Brett, hi Arnaud,

>  Just to say that this is really great work!  Kudos to you and Luca.
...
> I would just like to add that this is really much appreciated work!

Thanks !
I hope that the renewed look (together with the "always up to date with
zero maintainer work") will help to show to a the wider community that the
zeromq project is still there; there are users and it's a valid alternative
to other (perhaps more popular) messaging frameworks like Kafka, Pulsar or
NATS.
In this regard, in the future I would like to write some blog post on
the topic "ZeroMQ inside Kubernetes".  I have accumulated quite a long
(>3yrs) experience in running ZeroMQ services in scalable workloads inside
Kubernetes and developed a number of techniques to address problems
inherently connected to peer-to-peer (brokerless) communications.

Anyway, for now I think we should "finish" the documentation effort.
About that:

> * In master branch docs: Fix the "See Also" sections in the doc pages, by
using unordered lists, instead of space-separated single-line list

this has been done & merged

> * In api.zeromq.org wikidot: Setup the redirection to the new website;
according to https://www.wikidot.com/doc-modules:redirect-module, it's
enough to put
>    [[module Redirect destination="https://zeromq.readthedocs.io/en/latest/
"]]
>   in the wiki page... Luca / Kevin, my understanding is that you have
administrative access to the wikidot for api.zeromq.org... can you try
setting up this redirect?

this has been done by Luca

>* In zeromq.org website: Update the link "Low-level API" to point to
https://zeromq.readthedocs.io/en/latest/
>* In zeromq.org website: Create a page to host the contents of
http://wiki.zeromq.org/docs:contributing
>* In master branch docs: Update the link in the "Authors" sections to
point to the corresponding new page of the "new" zeromq.org website

For these steps I opened a first MR on zeromq.org repo:
https://github.com/zeromq/zeromq.org/pull/141
and I'm waiting for some feedback from Kevin Sapper which looks like the
de-facto maintainer of the zeromq.org website (looking at commit history) :)


> I'm also curious how we can make this work from zproject. But that might
be a later step.

I have saved the (very basic / raw) script I used to convert the
Asciidoc-py format to the "modern" Asciidoc format, so I can share them or
run them on other docs if useful.
To be honest I never used any other project outside libzmq so I'm quite new
to e.g. czmq or zproject.

Thanks,
Francesco


Il giorno sab 4 nov 2023 alle ore 22:50 Arnaud Loonstra <arnaud at sphaero.org>
ha scritto:

> I would just like to add that this is really much appreciated work!
>
> I'm also curious how we can make this work from zproject. But that might
> be a later step.
>
> Rg,
>
> Arnaud
> On 03/11/2023 10:29, Francesco wrote:
>
> Hi all,
>
> As an update on this topic: with help from Luca the *conversion of
> documentation from the old Asciidoc-py has been completed*.
> As bonus: Github is able to render Asciidocs natively, so e.g. you can see
> the documentation rendered on the fly by just browsing Github repo, e.g.
> see https://github.com/zeromq/libzmq/blob/master/doc/zmq_connect.adoc.
> Additionally the docs get published to Github Pages:
>  https://zeromq.github.io/libzmq/ <https://zeromq.github.io/libzmq/>
>
> *The integration with ReadTheDocs is also complete*, you can check out
> the result at: https://zeromq.readthedocs.io/en/latest/
> Please note that from the flyout menu it's possible to browse docs for:
> libzmq 3.2.6, libzmq 4.0.10, libzmq 4.1.8, latest libzmq (master). Just
> like what we have in http://api.zeromq.org/.
> Unlike http://api.zeromq.org/ however, the ReadTheDocs website is
> automatically updated anytime there is a git checkin, so it will always
> show up-to-date documentation.
> Also the rendering of the page is using a bigger font and is somewhat less
> compact compared to http://api.zeromq.org/.
> Any comment is welcome.
>
> *Next steps* I think are:
> * In master branch docs: Fix the "See Also" sections in the doc pages, by
> using unordered lists, instead of space-separated single-line list
> * In zeromq.org website: Update the link "Low-level API" to point to
> https://zeromq.readthedocs.io/en/latest/
> * In api.zeromq.org wikidot: Setup the redirection to the new website;
> according to https://www.wikidot.com/doc-modules:redirect-module, it's
> enough to put
>     [[module Redirect destination="
> https://zeromq.readthedocs.io/en/latest/"]]
>    in the wiki page... Luca / Kevin, my understanding is that you have
> administrative access to the wikidot for api.zeromq.org... can you try
> setting up this redirect?
>
> Bonus:
> * In zeromq.org website: Create a page to host the contents of
> http://wiki.zeromq.org/docs:contributing
> * In master branch docs: Update the link in the "Authors" sections to
> point to the corresponding new page of the "new" zeromq.org website
>
> I will try to contribute some PRs to the zeromq.org website repo to
> address above points
>
> Thanks,
>
> Francesco
>
>
>
> Il giorno mar 24 ott 2023 alle ore 15:35 Francesco <
> francesco.montorsi at gmail.com> ha scritto:
>
>> Hi Brett,
>>
>>
>> FWIW, I think it is very reasonable to accept some syntax change in
>>> order to migrate to a better supported document compiler and to gain the
>>> new functionality of readthedocs.  So, for whatever it may be worth, I
>>> take back my initial opinion to leave the API .txt files as-is.
>>>
>>
>> Actually in my PR I'm proposing to rename all .txt files to .adoc to
>> clarify they use Asciidoc syntax. It's clearly the correct extension that
>> should be used according to Asciidoc online resources.
>> As per the content: I migrated them to use the more modern asciidoc
>> syntax.
>>
>>
>>> Francesco, I know you have already invested effort down the asciidoctor
>>> path but maybe it is worth considering to jump fully to a flavor of
>>> markdown (eg github's)?
>>>
>>
>> I'm not sure. Of course they're biased but Asciidoc community claims to
>> be better and a "more sound alternative" to Markdown, see:
>>    https://docs.asciidoctor.org/asciidoc/latest/asciidoc-vs-markdown/
>>
>> A less-biased comparison (much longer to read -- I didn't read it all) is
>> at:
>>   https://www.dewanahmed.com/markdown-asciidoc-restructuredtext/
>>
>>
>> Actually, when I
>>> started writing I half assumed they were in markdown and half assumed
>>> they were in some special markdown'ish GSL syntax and only later figured
>>> out they were asciidoc.  But then I got confused about how to compile
>>> them (ie,
>>> asciidoc-py vs asciidoctor that you described).  Certainly, my stumbles
>>> were due to my ignorance/assumptions but had the docs been in markdown,
>>> all these little frictions would not have shown up.  Again, opinion fwiw.
>>>
>> I totally agree.
>> I also contributed some fixes/new features in the past and documenting
>> them was tricky. The .txt extension does not help at all.
>> The use of archaic tools makes it very hard to the "casual" contributor
>> to see the actual documentation rendered.
>> Even more tricky: I was expecting api.zeromq.org to automatically get
>> updated after some time the PR was merged... I discovered it's not the case
>> :)
>>
>> Last but not least: my use case for spending a few hours on this PR /
>> documentation improvement was very simple: I noticed a very nice new option
>> (ZMQ_BUSY_POLL) in the release notes. Then I started to search for docs
>> to share with the rest of the teams. I found only the .txt version, nothing
>> I could easily link in an email or share with simplicity... that was the
>> trigger point... :)
>>
>>
>> Thanks,
>> Francesco
>>
>>
>>
> _______________________________________________
> zeromq-dev mailing listzeromq-dev at lists.zeromq.orghttps://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/20231104/aed3f332/attachment.htm>


More information about the zeromq-dev mailing list