Doc: Build documentation using ReadTheDocs

[dbaston]

What does this PR do?

Continues the work started in #8681 to provide a GDAL configuration to build documentation using ReadTheDocs. The primary motivations for using ReadTheDocs are to (1) display version-specific documentation and (2) render documentation for pull requests.

The documentation generated using this configuration is available for testing at https://gdal.readthedocs.io

Changes to documentation build process

There are some changes relative to the current documentation building process, which is managed by https://github.com/OSGeo/gdal/blob/master/.github/workflows/doc_build.yml

1. The dependency on the ghcr.io/osgeo/proj-docs container is removed.
2. Javadocs are now included in each build.
3. Redirects were previously managed by a script that created about 400 HTML files to forward to new pages (https://github.com/OSGeo/gdal/blob/master/doc/source/_extensions/redirects.py). In ReadTheDocs, these are managed by a combination of rules and hard-coded redirects. Unfortunately, the redirects are not included in the configuration file. I added a script that can be used to create them via the ReadTheDocs API.
4. Possibly related to 1 and 2, the documentation build process increases from about 11 minutes to about 20 minutes. However, in my experience putting this together the ReadTheDocs runners start immediately, while GitHub Actions may have a lag of an hour or more.

Tasklist

• Review
• Adjust for comments
• All CI builds and checks have passed

[coveralls]

coverage: 69.358% (+0.003%) from 69.355%
when pulling 0550a38 on dbaston:rtd
into 449d5f0 on OSGeo:master.

[rouault]

The following style overrides are not incorporated into the build process, although they could be. It wasn't clear to me what effect they had or if they were still necessary.

They are necessary to shorten the output. https://gdal.readthedocs.io/en/latest/drivers/raster/index.html has the table + bullet points with each driver whereas https://gdal.org/drivers/raster/index.html has only the table.

And "WARNING: unknown config value 'enable_redirects' in override, ignoring" in the Docs CI target will be solved by changing line 81 of .github/workflows/doc_build.yml

[dbaston]

They are necessary to shorten the output

Thanks - addressed in 17a56d4

I removed the GitHub docs build entirely in c3e92b8

[rouault]

shellcheck not happy: https://github.com/OSGeo/gdal/actions/runs/9999643810/job/27641003915?pr=10434

[dbaston]

4bbf9ce adds a redirect to send URLS like /api to /en/latest/api.

It occurs to me that some pages (Sponsors, Community, others?) should probably be kept up-to-date even for old branches. Backporting changes to branches would be annoying. I think we could redirect e.g. /en/3.9/sponsors to /en/latest/sponsors, even if /en/3.9/sponsors exists. But it could be surprising for a user who starts navigating from /en/3.9/api to /en/latest/sponsors to /en/latest/api.

[github-actions]

The GDAL project highly values your contribution and would love to see this work merged! Unfortunately this PR has not had any activity in the last 28 days and is being automatically marked as "stale". If you think this pull request should be merged, please check

• that all unit tests are passing

• that all comments by reviewers have been addressed

• that there is enough information for reviewers, in particular link
  to any issues which this pull request fixes

• that you have written unit tests where possible
  In case you should have any uncertainty, please leave a comment and we will be happy to help you proceed with this pull request.
  If there is no further activity on this pull request, it will be closed in 2 weeks.

[dbaston]

DNS has been updated; gdal.org is now pointing to ReadTheDocs.

[rouault]

@dbaston I assume we can now merge this PR?

[dbaston]

Done. I manually started a build doc build from the GDAL repo at https://readthedocs.org/projects/gdal/builds/25437338/

I'm looking into the GitHub integration so that builds happen automatically.