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 < [email protected]> 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 < > [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
