[zeromq-dev] ZeroMQ docs

Francesco francesco.montorsi at gmail.com
Fri Nov 24 22:25:57 CET 2023


Hi all,
Another small update on the documentation side, in case you are interested:

>* In zeromq.org website: Update the link "Low-level API" to point to
https://zeromq.readthedocs.io/en/latest/
Done

>* In zeromq.org website: Create a page to host the contents of
http://wiki.zeromq.org/docs:contributing
Done, this is the new page: https://zeromq.org/how-to-contribute/

>* In master branch docs: Update the link in the "Authors" sections to
point to the corresponding new page of the "new" zeromq.org website
Done

I think on documentation side what's really left is just to update links
still indexed by Google and other search engines like:
  http://api.zeromq.org/3-2:zmq-connect   -->
https://libzmq.readthedocs.io/en/zeromq3-x/zmq_connect.html

With the help of Kevin Sapper I'm trying to understand how to automatically
create such redirection from the api.zeromq.org site

Francesco


Il giorno sab 4 nov 2023 alle ore 23:30 Francesco <
francesco.montorsi at gmail.com> ha scritto:

> 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/20231124/abf1437e/attachment.htm>


More information about the zeromq-dev mailing list