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