[zeromq-dev] ZeroMQ docs

Francesco francesco.montorsi at gmail.com
Mon Nov 27 23:53:27 CET 2023


Hi all,

A final update on the ZeroMQ API documentation migration:

> 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

Also this step is now complete.
Now that HTTP redirections are in place I think it will take only a few
days for search engines like Google to catch up and show the readthedocs.io
website in their results

Francesco


Il giorno ven 24 nov 2023 alle ore 22:25 Francesco <
francesco.montorsi at gmail.com> ha scritto:

> 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/20231127/fc2cfde6/attachment.htm>


More information about the zeromq-dev mailing list