[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/ <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 <http://zeromq.org> website: Update the link 
> "Low-level API" to point to https://zeromq.readthedocs.io/en/latest/
> * In api.zeromq.org <http://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 <http://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 
> <http://zeromq.org> website
>
> I will try to contribute some PRs to the zeromq.org 
> <http://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
>     <http://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 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/66507519/attachment.htm>