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 <[email protected]> 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 < > [email protected]> 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 > [email protected]https://lists.zeromq.org/mailman/listinfo/zeromq-dev > > _______________________________________________ > zeromq-dev mailing list > [email protected] > https://lists.zeromq.org/mailman/listinfo/zeromq-dev >
_______________________________________________ zeromq-dev mailing list [email protected] https://lists.zeromq.org/mailman/listinfo/zeromq-dev
