Re: [zeromq-dev] ZeroMQ docs

[Francesco]

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 
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/ 
>
> *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 

Re: [zeromq-dev] ZeroMQ docs

[Arnaud Loonstra]

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/ 


*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 
 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