[gdal-dev] Building GDAL documentation with ReadTheDocs

[Greg Troxel]

Daniel Baston via gdal-dev <gdal-dev at lists.osgeo.org> writes:

> Hello,
>
> I've put together a configuration to build GDAL's documentation using
> ReadTheDocs. As far as I know, this is the simplest way of publishing
> version-specific documentation and rending documentation for pull
> requests. A current build of the documentation can be viewed at
> https://gdal.readthedocs.io/en/latest/. A pull request with the
> proposed configuration is available at
> https://github.com/OSGeo/gdal/pull/10434.
>
> If anyone has feedback about using ReadTheDocs for this project, or
> the specifics of the proposed configuration, please share it here or
> as a comment on the pull request.

I agree that version-specific doc publication and docs on PRs is nice.

With things that feel like hosted services, I always want to ask:

  1) Is the toolchain that we will be using 100% open source?

  2) Could we, if readthedocs.io shut down, or if we felt like it, easily
  switch to doing this all on an osgeo website?  Could we easily have
  downloads of browseable tarballs?  Could a random user easily check
  out the docs repo and (with 100% open source tooling) generate the
  docs?

  3) The website loads ads from "ethicalads.io":

    https://media.ethicalads.io/media/client/beta/ethicalads.min.js

  which is hard to read.  It loads something else that uBlock Origin
  objects to:

    https://readthedocs.org/api/v2/sustainability/data/?callback=jQuery360005151577479217162_1721754548069&format=jsonp&project=gdal&_=1721754548070

  which results in

    jQuery360005151577479217162_1721754548069({"ad_free":false,"campaign_types":["community","house","paid"],"keywords":["only words","readthedocs-project-1031375","readthedocs-project-gdal"],"publisher":"readthedocs"});

  and also loads self-hosted analytics:

    https://gdal.readthedocs.io/_/api/v2/analytics/?project=gdal&version=latest&absolute_uri=https%3A%2F%2Fgdal.readthedocs.io%2Fen%2Flatest%2F
    https://gdal.readthedocs.io/_/static/javascript/readthedocs-analytics.js

  I do not find a doc site privacy policy in a footer.  There is no GDPR
  cookie consent -- those can be dreadful, I know -- but I doubt "no
  cookies are set" is really how it is.   I have no fundamental problem
  with cookies -- I'm thinking about tracking.

I would say that if 1 or 2 is not ok, then I see this as problematic,
but I'm hoping they are both fine.

For 3, not sure what the community wants to do, but I'm mildly
uncomfortable.  It seems less bad than using github, but that doesn't
automatically make it ok :-)

In my view, docs should be part of a package build and installed so they
are available on the computer with the software.  If it's just sphinx,
that can just be part of the gdal build and installed to
$prefix/share/doc/gdal/html, optionally off, or buildable separately to
make the gdal-doc package.  This could be the same toolchain as RTD of
course.