[zeromq-dev] ZeroMQ docs

Francesco francesco.montorsi at gmail.com
Fri Nov 3 10:29:24 CET 2023


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


More information about the zeromq-dev mailing list