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