Daniel Baston via gdal-dev <gdal-dev@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@lists.osgeo.org https://lists.osgeo.org/mailman/listinfo/gdal-dev