Re: [zeromq-dev] ZeroMQ docs
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] ZeroMQ docs
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
Re: [zeromq-dev] ZeroMQ docs
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
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
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
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
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
