Moving docs from zeromq.readthedocs.io to libzmq.readthedocs.io

[f18m]

Issue

Currently we have bound the "zeromq/libzmq" project of Github to the "zeromq" project in RTD: https://readthedocs.org/projects/zeromq/.

In the meanwhile the RTD team has freed the "libzmq" project name for usage. The proposal on zeromq-dev mailing list is to move the docs then to the https://readthedocs.org/projects/libzmq/ location. RTD team is suggesting and will help us to setup a redirection from "zeromq" to "libzmq". Here's the excerpt from an email exchange with RTD support team:

Francesco wrote: I have a question though: is it possible somehow to register a single project ( https://github.com/zeromq/libzmq ) with 2 different names inside RTD? I'm asking because in the past week the libzmq official project was imported into RTD with the name "zeromq". Now that "libzmq" is available as well, I'm not sure how to proceed...

RTD support wrote: For cases like this, we recommend redirecting the old project to the new one, see https://docs.readthedocs.io/en/stable/user-defined-redirects.html#migrating-your-documentation-to-another-domain. I can enable the "forced" redirects feature for the zeromq project if you want to proceed with that option. ... I have enabled that feature for your project, you should be able to create a forced redirect now.

Solution

If you agree with the proposed change (see also https://www.mail-archive.com/zeromq-dev@lists.zeromq.org/msg31627.html) we can proceed with:

• removing the binding Github libzmq --> RTD zeromq
• register again the Github libzmq into RTD as "libzmq"
• setup the redirection from RTD "zeromq -> libzmq"

What do you think?

I think I can do such change autonomously actually but I wanted to get some agreement with maintainers first (of course!). We should also proceed with the plan "soon" before anybody else takes the "libzmq" project name on RTD possibly.

Thanks

[bluca]

Sure, go for it

[f18m]

doing it now. Unfortunately it was not possible to do the "removing the binding Github libzmq --> RTD zeromq". So I had to delete the zeromq project entirely. Will recreate it in a while

[f18m]

Ok I think I managed to fix the setup of the projects inside RTD. The situation now is:

• libzmq github is associated to the RTD "libzmq" project: https://libzmq.readthedocs.io/en/latest/
• the RTD "zeromq" project had to be associated to some git repository to allow its creation... so I created an empty github project https://github.com/zeromq/zeromq-readthedocs and bound it to the RTD "zeromq" project. In the future it might be used to generate some basic landing page to jump to libzmq, czmq, pyzmq docs, etc
• in the RTD "zeromq" project there is now an "exact redirect" that redirects any page from the https://zeromq.readthedocs.io domain to the https://libzmq.readthedocs.io domain

One thing we can do is update the api.zeromq.org redirection to point straight to the https://libzmq.readthedocs.io domain instead of https://zeromq.readthedocs.io domain...

Other than that, zeromq.org website updates are still pending, but I'm waiting for MR https://github.com/zeromq/zeromq.org/pull/141 to get merged first to estabilish a clean "baseline".

[bluca]

• the RTD "zeromq" project had to be associated to some git repository to allow its creation... so I created an empty github project https://github.com/zeromq/zeromq-readthedocs and bound it to the RTD "zeromq" project. In the future it might be used to generate some basic landing page to jump to libzmq, czmq, pyzmq docs, etc

Why not https://github.com/zeromq/zeromq.org ?

[bluca]

also previous versions seem to be missing on https://libzmq.readthedocs.io/

[f18m]

• the RTD "zeromq" project had to be associated to some git repository to allow its creation... so I created an empty github project https://github.com/zeromq/zeromq-readthedocs and bound it to the RTD "zeromq" project. In the future it might be used to generate some basic landing page to jump to libzmq, czmq, pyzmq docs, etc

Why not https://github.com/zeromq/zeromq.org ?

Because if in the future we find any need to create a landing page... then the github repo must be enhanced to contain a .readthedocs.yaml file, and contain some sort of HTML to act as landing page... overloading the zeromq.org repository as both "source for the netlify website" and "source for the RTD landing page" seems a bit confusing... but of course we can delete the zeromq RTD project and recreate it again binding it to https://github.com/zeromq/zeromq.org if we want.

[f18m]

also previous versions seem to be missing on https://libzmq.readthedocs.io/

I think it took a while for RTD to rebuild all versions.. try to refresh... right now I do see in the flyout menu all versions:

[f18m]

Closing this one because the conversion from zeromq to libzmq has been carried out successfully on RTD.