Feature: master: integrate with ReadTheDocs

f18m commented 8 months ago

This PR is a followup of my previous PR to modernize docs.

Here's my current draft: https://f18m-libzmq.readthedocs.io/en/latest/

As you can see compared to Github pages there is also a "flyout" menu in the bottom-right corner of the page that allows you:

to choose between "latest" (master) docs and some stable tag
to jump to the "downloads" section where you can download the PDF

I think this is an improvement compared to the http://api.zeromq.org/ website which is manually updated (rarely done due to the manual work it takes) and is based on a sort-of-abandoned platform (wikidot).

Current issues/gotchas I found so far are:

the new .readthedocs.yaml file contains the hardcoded version of the ZMQ library... I couldn't find a way to get the cmake/automake build work from within the RTD pipeline. What I can try is to pull the version from git somehow but my understanding is that there is no centralized place in the git repo with the libzmq version anyhow (e.g. the version is hardcoded in the .spec, in the debian changelog, etc). So probably having one moew file hardcoding the current version is not a big deal.
to host docs for past versions "4.2 stable", "4.1 stable", "4.0 stable" and "3.2 legacy" of libzmq (just like http://api.zeromq.org/ does) we need to: a) create a branch dedicated to each such release in the git repository of libzmq, b) add a .readthedocs.yaml file in such branch, c) fix some syntax in Asciidoc files in such branch (similarly to what has been done recently in 'master' branch)

Please note that at https://f18m-libzmq.readthedocs.io/en/latest/, I've imported docs only related to "4.2 stable" i.e. the tag 4.2.5. If this approach is accepted, I can open PRs to get docs also for other versions currently listed at api.zeromq.org (namely "4.1 stable", "4.0 stable" and "3.2 legacy"). Before I can open such PRs, I need some libzmq maintainer to actually create the branches by running:

git checkout -b releases/4.2.x v4.2.5
for oldver in releases/4.1.x releases/4.0.x releases/3.2.x; do
    git switch --orphan $oldver
    git commit --allow-empty -m "Initial commit on release branch created just for ReadTheDocs integration"
    git push -u origin $oldver
done

bluca commented 8 months ago

The landing page on api.zeromq.org has a full list of all manpages, any chance the same could be replicated in the new website?

bluca commented 8 months ago

to host docs for past versions "4.2 stable", "4.1 stable", "4.0 stable" and "3.2 legacy" of libzmq (just like http://api.zeromq.org/ does) we need to: a) create a branch dedicated to each such release in the git repository of libzmq, b) add a .readthedocs.yaml file in such branch, c) fix some syntax in Asciidoc files in such branch (similarly to what has been done recently in 'master' branch)

Can this be done in the respective stable repositories instead?

f18m commented 8 months ago

The landing page on api.zeromq.org has a full list of all manpages, any chance the same could be replicated in the new website?

yes this can be done -- I can open a separate PR to create automatically a new .adoc file listing all other .adoc files sorted alphabetically... I though that the zmq.adoc/html is actually a more user-friendly index page, but that's debatable

f18m commented 8 months ago

to host docs for past versions "4.2 stable", "4.1 stable", "4.0 stable" and "3.2 legacy" of libzmq (just like http://api.zeromq.org/ does) we need to: a) create a branch dedicated to each such release in the git repository of libzmq, b) add a .readthedocs.yaml file in such branch, c) fix some syntax in Asciidoc files in such branch (similarly to what has been done recently in 'master' branch)

Can this be done in the respective stable repositories instead?

The only RTD feature that gets close to that is the "subprojects" feature. However it's designed to cover a different use case: access from the "main project documentation" the documentation for related plugins/subprojects. I think that would be nice to handle e.g. documentation for libzmq bindings (if they move to RTD in the future as well).

I can give it a better try in my fork anyway also as "workaround solution" to provide docs for past libzmq versions

bluca commented 8 months ago

The landing page on api.zeromq.org has a full list of all manpages, any chance the same could be replicated in the new website?

yes this can be done -- I can open a separate PR to create automatically a new .adoc file listing all other .adoc files sorted alphabetically... I though that the zmq.adoc/html is actually a more user-friendly index page, but that's debatable

Maybe merge the two? IE, add the full list at the bottom of the new landing page?

f18m commented 8 months ago

The landing page on api.zeromq.org has a full list of all manpages, any chance the same could be replicated in the new website?

yes this can be done -- I can open a separate PR to create automatically a new .adoc file listing all other .adoc files sorted alphabetically... I though that the zmq.adoc/html is actually a more user-friendly index page, but that's debatable

Maybe merge the two? IE, add the full list at the bottom of the new landing page?

yes ok -- this sounds feasible, I'll open a different PR for that though since it's not directly related to RTD integration

f18m commented 8 months ago

to host docs for past versions "4.2 stable", "4.1 stable", "4.0 stable" and "3.2 legacy" of libzmq (just like http://api.zeromq.org/ does) we need to: a) create a branch dedicated to each such release in the git repository of libzmq, b) add a .readthedocs.yaml file in such branch, c) fix some syntax in Asciidoc files in such branch (similarly to what has been done recently in 'master' branch)

Can this be done in the respective stable repositories instead?

The only RTD feature that gets close to that is the "subprojects" feature. However it's designed to cover a different use case: access from the "main project documentation" the documentation for related plugins/subprojects. I think that would be nice to handle e.g. documentation for libzmq bindings (if they move to RTD in the future as well).

I can give it a better try in my fork anyway also as "workaround solution" to provide docs for past libzmq versions

Actually I tried this solution and it does not work the way I though: the subprojects will not appear in the flyout menu, which is what the users will expect from the RTD flyout menu.

E.g. I added my fork of "zeromq4-1" (with RTD integration) as subproject and now I have this link: https://f18m-libzmq.readthedocs.io/projects/v4-1-x/en/latest/ which works fine (as you can see it is served from the "f18m-libzmq" website and linked as "v4.1.x"). However it does not appear in the flyout menu and thus we should build some explicit link in the body of the documentation to make it accessible to the user.

I think using branches is a better match to the RTD model. I know that it's a trouble since libzmq has a different model for releases (i.e. using an entire detached git repo for each stable release)... but honestly it's not a very common pattern so it will be hard to find any tool supporting that. Using tags/release branches inside the same git repo is the standard way to deal with releases AFAICT...

bluca commented 8 months ago

That's fine, it is extremely unlikely those will ever get updated again anyway

f18m commented 8 months ago

That's fine, it is extremely unlikely those will ever get updated again anyway

you mean it's fine to go with RTD integration done inside git branches of "libzmq" repo (also for 4.1, 4.0, 3.2 releases)?

bluca commented 8 months ago

yes

f18m commented 8 months ago

yes

ok, great. Then I think we need to carry out, more or less in this sequence, the following steps:

1) this PR is merged to get the .readthedocs configuration in the master branch 2) @bluca you register at https://readthedocs.org/accounts/signup/ by using the "signup with GitHub" (this will make it easy to import libzmq into RTD) 3) you then click on "import a project" and choose zeromq/libzmq from the list; it has to be imported with a name like "zeromq" for now, because "libzmq" is already taken (see my mail on zeromq-dev mailing list about the recovery of the abandoned "libzmq" project on RTD) 4) if you want under Settings->Maintainer you can add myself as maintainer 5) then we need to create the branches for past versions of libzmq, for RTD integration:

# create branch for 4.2.x releases:
git checkout -b releases/4.2.x v4.2.5
git push

# create empty branches for older releases:
for oldver in releases/4.1.x releases/4.0.x releases/3.2.x; do
    git switch --orphan $oldver
    git commit --allow-empty -m "Initial commit on release branch created just for ReadTheDocs integration"
    git push -u origin $oldver
done

after that I can open PR against those branches to get there the .readthedocs.yaml file and the necessary Asciidoc tweaks. Currently github does not allow me to open a PR against a non-existing branch.

f18m commented 8 months ago

Btw thinking about my last comment: I can also create the project "zeromq" on RTD and add you as maintainer of that project (and perhaps any other maintainer that might be useful to have onboard for the future)... I think the final result will be the same. Whatever is easier for you.

bluca commented 8 months ago

I've created it, what's your username? Also the CI is failing here

f18m commented 8 months ago

I've created it, what's your username?

my username is "f18m" , email is francesco.montorsi@gmail.com

Also the CI is failing here

Very likely that's because hte .readthedocs.yaml file is missing... (we need to merge this PR)

bluca commented 8 months ago

I mean the CI for this PR, check the builds

bluca commented 8 months ago

I've pushed the legacy branches

f18m commented 8 months ago

I mean the CI for this PR, check the builds

I pushed an attempt to fix the builds that were failing... I'll check the OBS results for next build

I've pushed the legacy branches

ok thanks, I will open separate PRs

f18m commented 8 months ago

I mean the CI for this PR, check the builds

I pushed an attempt to fix the builds that were failing... I'll check the OBS results for next build

I think the builds are failing because Asciidoc conditionals were not supported (or supported differently) with the Asciidoctor 1.5.x present in Debian9 and Debian10. I posted a question on asciidoc forum to understand how to get it right.

Anyway a simpler fix is probably https://github.com/zeromq/libzmq/pull/4615 which removes the usage of "zmq.html" as "index.html" and provides a clear statement of the libzmq version being documented at the top of the page. So perhaps if https://github.com/zeromq/libzmq/pull/4615 can be merged, then I can rebase this PR.

f18m commented 8 months ago

The documentation produced by this branch is visible on my fork RTD: https://f18m-libzmq.readthedocs.io/en/latest/

bluca commented 8 months ago

Is this ready?

f18m commented 8 months ago

Is this ready?

Yes, it's ready and also all other PRs for other branches are ready as well

zeromq / libzmq

Feature: master: integrate with ReadTheDocs #4614