Re: [zeromq-dev] ZeroMQ docs

[Francesco]

Hi Luca,
thanks! Glad to help and give something back to the community!


Il giorno mar 28 nov 2023 alle ore 14:00 Luca Boccassi <
luca.bocca...@gmail.com> ha scritto:

> On Mon, 27 Nov 2023 at 22:56, Francesco 
> wrote:
> >
> > Hi all,
> >
> > A final update on the ZeroMQ API documentation migration:
> >
> > > 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
> >
> > Also this step is now complete.
> > Now that HTTP redirections are in place I think it will take only a few
> days for search engines like Google to catch up and show the
> readthedocs.io website in their results
> >
> > Francesco
>
> Excellent stuff, thank you
> ___
> 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

Re: [zeromq-dev] ZeroMQ docs

[Luca Boccassi]

On Mon, 27 Nov 2023 at 22:56, Francesco  wrote:
>
> Hi all,
>
> A final update on the ZeroMQ API documentation migration:
>
> > 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
>
> Also this step is now complete.
> Now that HTTP redirections are in place I think it will take only a few days 
> for search engines like Google to catch up and show the readthedocs.io 
> website in their results
>
> Francesco

Excellent stuff, thank you
___
zeromq-dev mailing list
zeromq-dev@lists.zeromq.org
https://lists.zeromq.org/mailman/listinfo/zeromq-dev

Re: [zeromq-dev] ZeroMQ docs

[Francesco]

Hi all,

A final update on the ZeroMQ API documentation migration:

> 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

Also this step is now complete.
Now that HTTP redirections are in place I think it will take only a few
days for search engines like Google to catch up and show the readthedocs.io
website in their results

Francesco


Il giorno ven 24 nov 2023 alle ore 22:25 Francesco <
francesco.monto...@gmail.com> ha scritto:

> 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 <
> francesco.monto...@gmail.com> 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 <
>> arn...@sphaero.org> 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 

Re: [zeromq-dev] ZeroMQ docs

[Francesco]

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 <
francesco.monto...@gmail.com> 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 <
> arn...@sphaero.org> 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/ 
>>
>> *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 

Re: [zeromq-dev] ZeroMQ docs

[Francesco]

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 
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/ 
>
> *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 

Re: [zeromq-dev] ZeroMQ docs

[Arnaud Loonstra]

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/ 


*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 
 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 

Re: [zeromq-dev] ZeroMQ docs

[Brett Viren via zeromq-dev]

Francesco  writes:

> Any comment is welcome.

Just to say that this is really great work!  Kudos to you and Luca.

-Brett.


signature.asc
Description: PGP signature
___
zeromq-dev mailing list
zeromq-dev@lists.zeromq.org
https://lists.zeromq.org/mailman/listinfo/zeromq-dev

Re: [zeromq-dev] ZeroMQ docs

[Francesco]

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/ 

*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 <
francesco.monto...@gmail.com> 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
zeromq-dev@lists.zeromq.org
https://lists.zeromq.org/mailman/listinfo/zeromq-dev

Re: [zeromq-dev] ZeroMQ docs

[Bob Eby]

I'm mostly a lurker and merely a user but:

I have to say ZeroMQ docs have been great for years.  If ZeroMQ docs
are on some "not 100% most popular" tool asciidoc instead of markdown.
Maybe the maintainers should just stick with what they like.

Monoculture is not a good thing.  If the only GUI on the planet was
GNOME I would kill myself or worse quit writing software.  Ditto if
git were the ONLY source control.  (Note that I do use BOTH GNOME and
git at times, but alternatives are a healthy thing and not to be
dismissed when they work well)

Just my two cents,

And thanks for all the contributions to ZeroMQ everyone  I love / rely
on this tool,
Robert E.
___
zeromq-dev mailing list
zeromq-dev@lists.zeromq.org
https://lists.zeromq.org/mailman/listinfo/zeromq-dev

Re: [zeromq-dev] ZeroMQ docs

[Francesco]

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
zeromq-dev@lists.zeromq.org
https://lists.zeromq.org/mailman/listinfo/zeromq-dev

Re: [zeromq-dev] ZeroMQ docs

[Brett Viren]

Francesco  writes:

> 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]

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.

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)?

Given the similarity between asciidoctor and markdown syntax, this
change would not be so large for both human editors and the
mass-replacement you are developing.  The additional benefit is that
having the API docs in markdown syntax would give libzmq more options
for building end-user document formats.

I guess these docs will not see much change going forward but as someone
who recently contributed a new one I can say that process would have
been easier if the API docs were in markdown format.  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.

-Brett.
___
zeromq-dev mailing list
zeromq-dev@lists.zeromq.org
https://lists.zeromq.org/mailman/listinfo/zeromq-dev

Re: [zeromq-dev] ZeroMQ docs

[Francesco]

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.monto...@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.vi...@gmail.com> ha scritto:
>
>> On Fri, Oct 20, 2023 at 12:03 PM Francesco 
>> 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://.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

Re: [zeromq-dev] ZeroMQ docs

[Francesco]

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 
ha scritto:

> On Fri, Oct 20, 2023 at 12:03 PM Francesco 
> 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://.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

Re: [zeromq-dev] ZeroMQ docs

[Brett Viren]

On Fri, Oct 20, 2023 at 12:03 PM Francesco  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://.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

Re: [zeromq-dev] ZeroMQ docs

[Kevin Sapper]

Hi Francesco,
the current API docs are indeed served by wikidot. There is a repo
https://github.com/zeromq/ztools which updates the docs. I do have the
permissions to logon and perform the update. I'll do the update sometime
next week.

In regards to the look of the API docs we can all agree they are
outdated and wikidot itself is a dead platform that is no longer maintained.

If you like you can have a look at how the wikidot syntax is generated in
the ztools project and then try to generate markdown or asciidoc instead.

 schrieb am Fr., 20. Okt. 2023, 17:06:

> hi Brett,
> thanks for your answer.
> I checked zeromq.org (I had some trouble using Docker to get the website
> up: https://github.com/zeromq/zeromq.org/issues/125 and then I installed
> locally hugo but I discovered it needs a quite old version 0.57.2 built in
> "extended" mode). I'm not really a web developer so I'm not sure how
> difficult it is to upgrade to latest "hugo" (
> https://github.com/gohugoio/hugo/).
> Anyway.
> The thing is that api.zeromq.org is probably served by some other source.
> I guess somebody has credentials to log on http://www.wikidot.com/ and
> update that page, but I don't think there is much to do in the "zeromq.org"
> repo. Of course I may be missing something.
>
> Personally, I think the look of api.zeromq.org is not the best one.
> readthedocs.io looks more like a de-facto standard for documentation in
> open source world (in my view)...
>
> thanks,
> Francesco
>
>
> Il giorno ven 20 ott 2023 alle ore 15:00 Brett Viren <
> brett.vi...@gmail.com> ha scritto:
>
>> Hi Francesco,
>>
>> I agree a refresh of the online API docs would be good.  I think the
>> zeromq.org website takes its content from:
>>
>>   https://github.com/zeromq/zeromq.org
>>
>> A PR to that repo is likely the first step to get zeromq.org updated.
>>
>> It would be extra good if the API docs for development and releases
>> could be refreshed in a more automated way.
>>
>>
>> I personally like having all the documentation under *.zeromq.org but I
>> see benefit and no downside to also having a copy of the API docs served
>> from readthedocs.
>>
>> The current API documentation source files are in AsciiDoc format under
>> libzmq/doc/*.txt and there are HTML and Unix man page build targets.
>> These should of course be retained.
>>
>> Readthedocs suggests a procedure to build from AsciiDoc sources.
>>
>>   https://docs.readthedocs.io/en/stable/build-customization.html#asciidoc
>>
>> Perhaps a PR to libzmq that adds something under libzmq/.github/ is the
>> path to get this new API doc target working?
>>
>>
>> -Brett.
>>
>> On Fri, Oct 20, 2023 at 6:09 AM Francesco 
>> wrote:
>> >
>> > Another point I forgot: I think it would be nice to switch to
>> https://about.readthedocs.com/ as  a way to publish the libzmq API...
>> >
>> >
>> > Il giorno ven 20 ott 2023 alle ore 12:00 Francesco <
>> francesco.monto...@gmail.com> ha scritto:
>> >>
>> >> Hi all,
>> >> I'm happy to see that version 4.3.5 has been published, thanks Luca
>> and all other contributors for making that happen!
>> >>
>> >> However I noticed that http://api.zeromq.org/master:_start is still
>> mentioning version 4.3.2 of the API.
>> >>
>> >> Do you think it's possible to get there updated docs?
>> >> If there is any work to be done, I can try to help the best I can...
>> >>
>> >> Thanks,
>> >> Francesco
>> >>
>> >>
>> > ___
>> > 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
>
___
zeromq-dev mailing list
zeromq-dev@lists.zeromq.org
https://lists.zeromq.org/mailman/listinfo/zeromq-dev

Re: [zeromq-dev] ZeroMQ docs

[Francesco]

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?




Il giorno ven 20 ott 2023 alle ore 17:03 Francesco <
francesco.monto...@gmail.com> ha scritto:

> hi Brett,
> thanks for your answer.
> I checked zeromq.org (I had some trouble using Docker to get the website
> up: https://github.com/zeromq/zeromq.org/issues/125 and then I installed
> locally hugo but I discovered it needs a quite old version 0.57.2 built in
> "extended" mode). I'm not really a web developer so I'm not sure how
> difficult it is to upgrade to latest "hugo" (
> https://github.com/gohugoio/hugo/).
> Anyway.
> The thing is that api.zeromq.org is probably served by some other source.
> I guess somebody has credentials to log on http://www.wikidot.com/ and
> update that page, but I don't think there is much to do in the "zeromq.org"
> repo. Of course I may be missing something.
>
> Personally, I think the look of api.zeromq.org is not the best one.
> readthedocs.io looks more like a de-facto standard for documentation in
> open source world (in my view)...
>
> thanks,
> Francesco
>
>
> Il giorno ven 20 ott 2023 alle ore 15:00 Brett Viren <
> brett.vi...@gmail.com> ha scritto:
>
>> Hi Francesco,
>>
>> I agree a refresh of the online API docs would be good.  I think the
>> zeromq.org website takes its content from:
>>
>>   https://github.com/zeromq/zeromq.org
>>
>> A PR to that repo is likely the first step to get zeromq.org updated.
>>
>> It would be extra good if the API docs for development and releases
>> could be refreshed in a more automated way.
>>
>>
>> I personally like having all the documentation under *.zeromq.org but I
>> see benefit and no downside to also having a copy of the API docs served
>> from readthedocs.
>>
>> The current API documentation source files are in AsciiDoc format under
>> libzmq/doc/*.txt and there are HTML and Unix man page build targets.
>> These should of course be retained.
>>
>> Readthedocs suggests a procedure to build from AsciiDoc sources.
>>
>>   https://docs.readthedocs.io/en/stable/build-customization.html#asciidoc
>>
>> Perhaps a PR to libzmq that adds something under libzmq/.github/ is the
>> path to get this new API doc target working?
>>
>>
>> -Brett.
>>
>> On Fri, Oct 20, 2023 at 6:09 AM Francesco 
>> wrote:
>> >
>> > Another point I forgot: I think it would be nice to switch to
>> https://about.readthedocs.com/ as  a way to publish the libzmq API...
>> >
>> >
>> > Il giorno ven 20 ott 2023 alle ore 12:00 Francesco <
>> francesco.monto...@gmail.com> ha scritto:
>> >>
>> >> Hi all,
>> >> I'm happy to see that version 4.3.5 has been published, thanks Luca
>> and all other contributors for making that happen!
>> >>
>> >> However I noticed that http://api.zeromq.org/master:_start is still
>> mentioning version 4.3.2 of the API.
>> >>
>> >> Do you think it's possible to get there updated docs?
>> >> If there is any work to be done, I can try to help the best I can...
>> >>
>> >> Thanks,
>> >> Francesco
>> >>
>> >>
>> > ___
>> > 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

Re: [zeromq-dev] ZeroMQ docs

[Francesco]

hi Brett,
thanks for your answer.
I checked zeromq.org (I had some trouble using Docker to get the website
up: https://github.com/zeromq/zeromq.org/issues/125 and then I installed
locally hugo but I discovered it needs a quite old version 0.57.2 built in
"extended" mode). I'm not really a web developer so I'm not sure how
difficult it is to upgrade to latest "hugo" (
https://github.com/gohugoio/hugo/).
Anyway.
The thing is that api.zeromq.org is probably served by some other source. I
guess somebody has credentials to log on http://www.wikidot.com/ and update
that page, but I don't think there is much to do in the "zeromq.org" repo.
Of course I may be missing something.

Personally, I think the look of api.zeromq.org is not the best one.
readthedocs.io looks more like a de-facto standard for documentation in
open source world (in my view)...

thanks,
Francesco


Il giorno ven 20 ott 2023 alle ore 15:00 Brett Viren 
ha scritto:

> Hi Francesco,
>
> I agree a refresh of the online API docs would be good.  I think the
> zeromq.org website takes its content from:
>
>   https://github.com/zeromq/zeromq.org
>
> A PR to that repo is likely the first step to get zeromq.org updated.
>
> It would be extra good if the API docs for development and releases
> could be refreshed in a more automated way.
>
>
> I personally like having all the documentation under *.zeromq.org but I
> see benefit and no downside to also having a copy of the API docs served
> from readthedocs.
>
> The current API documentation source files are in AsciiDoc format under
> libzmq/doc/*.txt and there are HTML and Unix man page build targets.
> These should of course be retained.
>
> Readthedocs suggests a procedure to build from AsciiDoc sources.
>
>   https://docs.readthedocs.io/en/stable/build-customization.html#asciidoc
>
> Perhaps a PR to libzmq that adds something under libzmq/.github/ is the
> path to get this new API doc target working?
>
>
> -Brett.
>
> On Fri, Oct 20, 2023 at 6:09 AM Francesco 
> wrote:
> >
> > Another point I forgot: I think it would be nice to switch to
> https://about.readthedocs.com/ as  a way to publish the libzmq API...
> >
> >
> > Il giorno ven 20 ott 2023 alle ore 12:00 Francesco <
> francesco.monto...@gmail.com> ha scritto:
> >>
> >> Hi all,
> >> I'm happy to see that version 4.3.5 has been published, thanks Luca and
> all other contributors for making that happen!
> >>
> >> However I noticed that http://api.zeromq.org/master:_start is still
> mentioning version 4.3.2 of the API.
> >>
> >> Do you think it's possible to get there updated docs?
> >> If there is any work to be done, I can try to help the best I can...
> >>
> >> Thanks,
> >> Francesco
> >>
> >>
> > ___
> > 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

Re: [zeromq-dev] ZeroMQ docs

[Brett Viren]

Hi Francesco,

I agree a refresh of the online API docs would be good.  I think the
zeromq.org website takes its content from:

  https://github.com/zeromq/zeromq.org

A PR to that repo is likely the first step to get zeromq.org updated.

It would be extra good if the API docs for development and releases
could be refreshed in a more automated way.


I personally like having all the documentation under *.zeromq.org but I
see benefit and no downside to also having a copy of the API docs served
from readthedocs.

The current API documentation source files are in AsciiDoc format under
libzmq/doc/*.txt and there are HTML and Unix man page build targets.
These should of course be retained.

Readthedocs suggests a procedure to build from AsciiDoc sources.

  https://docs.readthedocs.io/en/stable/build-customization.html#asciidoc

Perhaps a PR to libzmq that adds something under libzmq/.github/ is the
path to get this new API doc target working?


-Brett.

On Fri, Oct 20, 2023 at 6:09 AM Francesco  wrote:
>
> Another point I forgot: I think it would be nice to switch to 
> https://about.readthedocs.com/ as  a way to publish the libzmq API...
>
>
> Il giorno ven 20 ott 2023 alle ore 12:00 Francesco 
>  ha scritto:
>>
>> Hi all,
>> I'm happy to see that version 4.3.5 has been published, thanks Luca and all 
>> other contributors for making that happen!
>>
>> However I noticed that http://api.zeromq.org/master:_start is still 
>> mentioning version 4.3.2 of the API.
>>
>> Do you think it's possible to get there updated docs?
>> If there is any work to be done, I can try to help the best I can...
>>
>> Thanks,
>> Francesco
>>
>>
> ___
> 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

Re: [zeromq-dev] ZeroMQ docs

[Francesco]

Another point I forgot: I think it would be nice to switch to
https://about.readthedocs.com/ as  a way to publish the libzmq API...


Il giorno ven 20 ott 2023 alle ore 12:00 Francesco <
francesco.monto...@gmail.com> ha scritto:

> Hi all,
> I'm happy to see that version 4.3.5 has been published, thanks Luca and
> all other contributors for making that happen!
>
> However I noticed that http://api.zeromq.org/master:_start is still
> mentioning version 4.3.2 of the API.
>
> Do you think it's possible to get there updated docs?
> If there is any work to be done, I can try to help the best I can...
>
> Thanks,
> Francesco
>
>
>
___
zeromq-dev mailing list
zeromq-dev@lists.zeromq.org
https://lists.zeromq.org/mailman/listinfo/zeromq-dev