[gdal-dev] Building GDAL documentation with ReadTheDocs

[Daniel Baston]

> Could a random user easily check
> out the docs repo and (with 100% open source tooling) generate the
> docs?

Yes, we are currently and would continue to use Sphinx for the
documentation build.

Dan



On Tue, Jul 23, 2024 at 1:18 PM Greg Troxel via gdal-dev
<gdal-dev at lists.osgeo.org> wrote:
>
> 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.
>
> _______________________________________________
> gdal-dev mailing list
> gdal-dev at lists.osgeo.org
> https://lists.osgeo.org/mailman/listinfo/gdal-dev