[prev in list] [next in list] [prev in thread] [next in thread]
List: zeromq-dev
Subject: Re: [zeromq-dev] *** SPAM *** Re: ZeroMQ docs
From: Francesco <francesco.montorsi () gmail ! com>
Date: 2023-10-24 9:33:22
Message-ID: CAKW0qignPfNnSUjsJq9qAeA932Gpy93BiB+RgTQ4PF8mfkrZ5Q () mail ! gmail ! com
[Download RAW message or body]
[Attachment #2 (multipart/alternative)]
Hi Fabrice,
Thanks for the pointer.
Pandoc however seems to be able to convert only _to_ Asciidoc, not _from_
Asciidoc (by looking at https://pandoc.org/).
Anyway, thanks to some regex I managed to upgrade the format of the
Asciidoc documentation from the legacy format to the "modern/current"
Asciidoc format.
I have updated the PR at https://github.com/zeromq/libzmq/pull/4607
Documentation rendered as Github Pages in my own fork:
https://f18m.github.io/libzmq/
Any comment is welcome
Thanks,
Francesco
Il giorno mar 24 ott 2023 alle ore 09:20 Fabrice Bacchella <
fabrice.bacchella@orange.fr> ha scritto:
> Did you try pandoc ?
>
> Le 23 oct. 2023 à 23:16, Francesco <francesco.montorsi@gmail.com> a écrit
> >
>
> Update: apparently the point a) is blocked by point b).
>
> In more details: the Asciidoc modern syntax to get a cross-reference
> correctly rendered in both manpages and HTMLs is:
>
> xref:name_of_doc.adoc[name_of_doc]
>
> This will produce a valid link to "name_of_doc.html" for HTML output and a
> simple "name_of_doc" span of text for manpage output. This is the fix
> mentioned in step a).
> However this syntax is accepted only when Asciidoctor is NOT running in
> legacy/deprecated mode.
> To avoid that, I first need step b).
>
> Shall I put steps a) and b) together in my same WIP PR ?
> It will be harder to review it...
>
> thanks
>
>
> Il giorno lun 23 ott 2023 alle ore 22:43 Francesco <
> francesco.montorsi@gmail.com> ha scritto:
>
> > Hi all,
> >
> > Here's an update on my attempt to refresh the doc system for libzmq API.
> >
> > *Current status:*
> > libzmq is built around the "ancient" python Asciidoc tool. That tool is
> > unmaintained for several years and has been replaced by the Asciidoctor
> > tool (see
> > https://docs.asciidoctor.org/asciidoctor/latest/migrate/asciidoc-py/).
> > Note that the original tool used for interpreting the .txt files was
> > named "asciidoc" just like the language markup contained in the .txt files
> > itself. To avoid confusion, that tool is now referred to as "asciidoc-py".
> > The tool asciidoc-py is the one unmaintained. The language Asciidoc
> > itself instead is still maintained and developed, but Asciidoctor is the
> > only updated tool to process Asciidoc documents.
> > The manpages are built today in libzmq through this chain:
> > .txt --[asciidoc]--> .xml docbook --[xmlto]--> .3 or .7
> > manpages
> > where the [] indicate the tool used for the conversion. Also the
> > utility "xmlto" seems quite unmaintained.
> > Finally the wikidot website http://api.zeromq.org/ is built from some
> > scripts located in the "ztools" repo that basically leverages the ability
> > of that wiki to produce a listing of all wiki pages uploaded by group; the
> > group used is the ZMQ API version. This makes it possible to document
> > multiple versions of the libzmq API in the same website/wiki. However
> > wikidot itself seems unmaintained as well.
> >
> > *Where I got so far:*
> > I managed to convert to obtain usable and nicely-formatted HTML docs
> > running Asciidoctor on libzmq docs, after some mass-replacement passes to
> > fix some syntax issues.
> > Asciidoctor is still processing all libzmq docs using the so-called
> > "compatibility mode".
> > In my libzmq fork I enabled Github pages and I got them deployed on
> > every checkin of my branch.
> > Documentation rendered as Github Pages in my own fork:
> > https://f18m.github.io/libzmq/
> > PR: https://github.com/zeromq/libzmq/pull/4607
> >
> > *Next steps:*
> > a) I'm fighting a little bit with Asciidoctor to get the right
> > rendering also for manpages.
> > b) Some smart mass-replace is still needed to convert from the
> > deprecated Asciidoc format to the "modern" Asciidoc (see
> > https://docs.asciidoctor.org/asciidoctor/latest/migrate/asciidoc-py/#updated-and-deprecated-asciidoc-syntax
> > )
> > c) The Github pages approach is able to deploy only the documentation
> > for the latest "master" branch. Maintaining documentation for the multiple
> > API versions is probably best achieved using the more popular
> > readthedocs.io. As pointed out already in this email thread,
> > readthedocs.io is mostly designed around Sphinx and MkDocs but most
> > recent versions are flexible enough to accomodate also Asciidoc
> > documentation. I think eadthedocs.io is the best solution to store
> > different versions of libzmq API.
> >
> > Please let me know if you have any comments.
> > In my opinion to simplify the PR review, after step a) it's best to do a
> > first merge, and then carry out points b) and c) in 2 more separate PRs.
> >
> > What do you think?
> >
> > Thanks,
> >
> >
> >
> > Il giorno ven 20 ott 2023 alle ore 18:19 Brett Viren <
> > brett.viren@gmail.com> ha scritto:
> >
> > > On Fri, Oct 20, 2023 at 12:03 PM Francesco <francesco.montorsi@gmail.com>
> > > wrote:
> > > >
> > > > Maybe an even simpler solution is to activate the Github "Pages"
> > > support in libzmq.org and link it with a github action that just uses
> > > the Asciidoctor generator to convert all of doc/*.txt into static HTML.
> > > >
> > > > What do you think about this?
> > >
> > > This sounds like a very good idea to me. And, it's even easier as the
> > > existing libzmq build already produces the HTML.
> > >
> > > On could prototype some additional build action that populate the
> > > special gh-pages by committing these generated HTML files. This can
> > > be tested using a personal fork of libzmq to make your own
> > > https://<name>.github.io/libzmq/. When that works, a PR to libzmq
> > > would be needed. Bonus if some .github/ CI bits could automate this.
> > > And, someone with GitHub permissions would need to go into libzmq's
> > > repo settings to turn on the publish setting.
> > >
> > > -Brett.
> > > _______________________________________________
> > > zeromq-dev mailing list
> > > zeromq-dev@lists.zeromq.org
> > > https://lists.zeromq.org/mailman/listinfo/zeromq-dev
> > >
> > _______________________________________________
> zeromq-dev mailing list
> zeromq-dev@lists.zeromq.org
> https://lists.zeromq.org/mailman/listinfo/zeromq-dev
>
>
> _______________________________________________
> zeromq-dev mailing list
> zeromq-dev@lists.zeromq.org
> https://lists.zeromq.org/mailman/listinfo/zeromq-dev
>
[Attachment #5 (text/html)]
<div dir="ltr"><div dir="ltr">Hi Fabrice,</div><div>Thanks for the \
pointer.</div><div>Pandoc however seems to be able to convert only _to_ Asciidoc, not \
_from_ Asciidoc (by looking at <a href="https://pandoc.org/" \
target="_blank">https://pandoc.org/</a>).</div><div>Anyway, thanks to some regex I \
managed to upgrade the format of the Asciidoc documentation from the legacy format to \
the "modern/current" Asciidoc format.</div><div><br></div><div>I have \
updated the PR at <a href="https://github.com/zeromq/libzmq/pull/4607" \
target="_blank">https://github.com/zeromq/libzmq/pull/4607</a></div><div>Documentation \
rendered as Github Pages in my own fork: <a \
href="https://f18m.github.io/libzmq/">https://f18m.github.io/libzmq/</a></div><div><br></div><div>Any \
comment is welcome</div><div><br></div><div>Thanks,</div><div>Francesco </div><div> \
</div><br><div class="gmail_quote"><div dir="ltr" class="gmail_attr">Il giorno mar 24 \
ott 2023 alle ore 09:20 Fabrice Bacchella <<a \
href="mailto:fabrice.bacchella@orange.fr" \
target="_blank">fabrice.bacchella@orange.fr</a>> ha scritto:<br></div><blockquote \
class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid \
rgb(204,204,204);padding-left:1ex"><div>Did you try pandoc ?<br><div><br><blockquote \
type="cite"><div>Le 23 oct. 2023 Ã 23:16, Francesco <<a \
href="mailto:francesco.montorsi@gmail.com" \
target="_blank">francesco.montorsi@gmail.com</a>> a écrit :</div><br><div><div \
dir="ltr">Update: apparently the point a) is blocked by point \
b).<div><br></div><div>In more details: the Asciidoc modern syntax to get a \
cross-reference correctly rendered in both manpages and HTMLs \
is:</div><div><br></div><div> \
xref:name_of_doc.adoc[name_of_doc]</div><div><br></div><div>This will produce a valid \
link to "name_of_doc.html" for HTML output and a simple \
"name_of_doc" span of text for manpage output. This is the fix mentioned in \
step a).</div><div>However this syntax is accepted only when Asciidoctor is NOT \
running in legacy/deprecated mode.</div><div>To avoid that, I first need step b). \
</div><div><br></div><div>Shall I put steps a) and b) together in my same WIP PR ? \
</div><div>It will be harder to review \
it...</div><div><br></div><div>thanks</div><div><br></div></div><br><div \
class="gmail_quote"><div dir="ltr" class="gmail_attr">Il giorno lun 23 ott 2023 alle \
ore 22:43 Francesco <<a href="mailto:francesco.montorsi@gmail.com" \
target="_blank">francesco.montorsi@gmail.com</a>> ha scritto:<br></div><blockquote \
class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid \
rgb(204,204,204);padding-left:1ex"><div dir="ltr">Hi \
all,<div><br></div><div>Here's an update on my attempt to refresh the doc system \
for libzmq API.</div><div><br></div><div><b>Current status:</b></div><div> libzmq \
is built around the "ancient" python Asciidoc tool. That tool is \
unmaintained for several years and has been replaced by the Asciidoctor tool (see <a \
href="https://docs.asciidoctor.org/asciidoctor/latest/migrate/asciidoc-py/" \
target="_blank">https://docs.asciidoctor.org/asciidoctor/latest/migrate/asciidoc-py/</a>). \
</div><div> Note that the original tool used for interpreting the .txt files was \
named "asciidoc" just like the language markup contained in the .txt files \
itself. To avoid confusion, that tool is now referred to as "asciidoc-py". \
</div><div> The tool asciidoc-py is the one unmaintained. The language Asciidoc \
itself instead is still maintained and developed, but Asciidoctor is the only updated \
tool to process Asciidoc documents.</div><div> The manpages are built today in \
libzmq through this chain:</div><div> .txt --[asciidoc]--> .xml \
docbook --[xmlto]--> .3 or .7 manpages</div><div> where the [] \
indicate the tool used for the conversion. Also the utility "xmlto" seems \
quite unmaintained.</div><div> Finally the wikidot website <a \
href="http://api.zeromq.org/" target="_blank">http://api.zeromq.org/</a> is built \
from some scripts located in the "ztools" repo that basically leverages the \
ability of that wiki to produce a listing of all wiki pages uploaded by group; the \
group used is the ZMQ API version. This makes it possible to document multiple \
versions of the libzmq API in the same website/wiki. However wikidot itself seems \
unmaintained as well.</div><div><br></div><div><b>Where I got so \
far:</b><br></div><div><b> </b>I managed to convert to obtain usable and \
nicely-formatted HTML docs running Asciidoctor on libzmq docs, after some \
mass-replacement passes to fix some syntax issues. </div><div> Asciidoctor is \
still processing all libzmq docs using the so-called "compatibility mode". \
</div><div> In my libzmq fork I enabled Github pages and I got them deployed on \
every checkin of my branch.</div><div> Documentation rendered as Github Pages in my \
own fork: <a href="https://f18m.github.io/libzmq/" \
target="_blank">https://f18m.github.io/libzmq/</a> </div><div> PR: <a \
href="https://github.com/zeromq/libzmq/pull/4607" \
target="_blank">https://github.com/zeromq/libzmq/pull/4607</a></div><div><br></div><div><b>Next \
steps:</b></div><div> a) I'm fighting a little bit with Asciidoctor to get the \
right rendering also for manpages.</div><div> b) Some smart mass-replace is still \
needed to convert from the deprecated Asciidoc format to the "modern" \
Asciidoc (see <a href="https://docs.asciidoctor.org/asciidoctor/latest/migrate/asciidoc-py/#updated-and-deprecated-asciidoc-syntax" \
target="_blank">https://docs.asciidoctor.org/asciidoctor/latest/migrate/asciidoc-py/#updated-and-deprecated-asciidoc-syntax</a>)</div><div> \
c) The Github pages approach is able to deploy only the documentation for the latest \
"master" branch. Maintaining documentation for the multiple API versions is \
probably best achieved using the more popular <a href="http://readthedocs.io/" \
target="_blank">readthedocs.io</a>. As pointed out already in this email thread, <a \
href="http://readthedocs.io/" target="_blank">readthedocs.io</a> is mostly designed \
around Sphinx and MkDocs but most recent versions are flexible enough to accomodate \
also Asciidoc documentation. I think <a href="http://eadthedocs.io/" \
target="_blank">eadthedocs.io</a> is the best solution to store different versions of \
libzmq API.</div><div><br></div><div>Please let me know if you have any \
comments.</div><div>In my opinion to simplify the PR review, after step a) it's \
best to do a first merge, and then carry out points b) and c) in 2 more separate \
PRs.</div><div><br></div><div>What do you \
think?</div><div><br></div><div>Thanks,</div><div><br></div><div><br></div></div><br><div \
class="gmail_quote"><div dir="ltr" class="gmail_attr">Il giorno ven 20 ott 2023 alle \
ore 18:19 Brett Viren <<a href="mailto:brett.viren@gmail.com" \
target="_blank">brett.viren@gmail.com</a>> ha scritto:<br></div><blockquote \
class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid \
rgb(204,204,204);padding-left:1ex">On Fri, Oct 20, 2023 at 12:03 PM Francesco \
<<a href="mailto:francesco.montorsi@gmail.com" \
target="_blank">francesco.montorsi@gmail.com</a>> wrote:<br> ><br>
> Maybe an even simpler solution is to activate the Github "Pages" \
support in <a href="http://libzmq.org/" rel="noreferrer" \
target="_blank">libzmq.org</a> and link it with a github action that just uses the \
Asciidoctor generator to convert all of doc/*.txt into static HTML.<br> ><br>
> What do you think about this?<br>
<br>
This sounds like a very good idea to me. And, it's even easier as the<br>
existing libzmq build already produces the HTML.<br>
<br>
On could prototype some additional build action that populate the<br>
special gh-pages by committing these generated HTML files. This can<br>
be tested using a personal fork of libzmq to make your own<br>
https://<name>.<a href="http://github.io/libzmq/" rel="noreferrer" \
target="_blank">github.io/libzmq/</a>. When that works, a PR to libzmq<br> would be \
needed. Bonus if some .github/ CI bits could automate this.<br> And, someone with \
GitHub permissions would need to go into libzmq's<br> repo settings to turn on \
the publish setting.<br> <br>
-Brett.<br>
_______________________________________________<br>
zeromq-dev mailing list<br>
<a href="mailto:zeromq-dev@lists.zeromq.org" \
target="_blank">zeromq-dev@lists.zeromq.org</a><br> <a \
href="https://lists.zeromq.org/mailman/listinfo/zeromq-dev" rel="noreferrer" \
target="_blank">https://lists.zeromq.org/mailman/listinfo/zeromq-dev</a><br> \
</blockquote></div> </blockquote></div>
_______________________________________________<br>zeromq-dev mailing list<br><a \
href="mailto:zeromq-dev@lists.zeromq.org" \
target="_blank">zeromq-dev@lists.zeromq.org</a><br><a \
href="https://lists.zeromq.org/mailman/listinfo/zeromq-dev" \
target="_blank">https://lists.zeromq.org/mailman/listinfo/zeromq-dev</a><br></div></blockquote></div><br></div>_______________________________________________<br>
zeromq-dev mailing list<br>
<a href="mailto:zeromq-dev@lists.zeromq.org" \
target="_blank">zeromq-dev@lists.zeromq.org</a><br> <a \
href="https://lists.zeromq.org/mailman/listinfo/zeromq-dev" rel="noreferrer" \
target="_blank">https://lists.zeromq.org/mailman/listinfo/zeromq-dev</a><br> \
</blockquote></div></div>
_______________________________________________
zeromq-dev mailing list
zeromq-dev@lists.zeromq.org
https://lists.zeromq.org/mailman/listinfo/zeromq-dev
[prev in list] [next in list] [prev in thread] [next in thread]
Configure |
About |
News |
Add a list |
Sponsored by KoreLogic