Re: [gdal-dev] Building GDAL documentation with ReadTheDocs
> From what I see, robots.txt is automatically configured for the default > version: > https://docs.readthedocs.io/en/stable/reference/robots.html I read this as saying that the robots.txt published by the default branch will be served from the top level of the domain (https://proj.org/robots.txt) and that a robots.txt associated with any other branch will be ignored. If no robots.txt is provided, ReadTheDocs uses a default which allows indexing of all non-hidden branches. PROJ does not appear to have any branches that are hidden with RTD, so all versions >= 5.0 would be indexed. User-agent: * Disallow: # Allow everything Sitemap: https://proj.org/sitemap.xml Dan ___ gdal-dev mailing list gdal-dev@lists.osgeo.org https://lists.osgeo.org/mailman/listinfo/gdal-dev
Re: [gdal-dev] Building GDAL documentation with ReadTheDocs
Thanks, Rob. I've added a robots.txt to the PR (using /en/latest/, since /en/stable/ is not yet published) Dan On Wed, Jul 24, 2024 at 7:44 AM Robert Coup via gdal-dev wrote: > > On Wed, 24 Jul 2024 at 12:27, Even Rouault wrote: > > > > > > Le 24/07/2024 à 12:33, Javier Jimenez Shaw via gdal-dev a écrit : > > > >> I see the point, and I agree... but I don't know if it will work > >> RTD redirects to whatever we configure. In proj.org it is going directly > >> to 9.4 (current latest release). > > > > Seems like a good idea and something that can be easily be tuned by editing > > https://readthedocs.org/dashboard/osgeo-proj/edit/ . But when looking at > > https://proj.org/en/stable/about.html for example, the only thing that is > > missing to me is a hint of what "stable" alias to. So you have on the top > > left, under the PROJ logo, a "stable" text. It would be nice if that would > > be "stable (9.4)". Not sure if that can be tuned. > > > > So every 6 months it points to something different. Telling in robots.txt > > that the full page has a different URL is not good for seo and history (if > > I understand correctly how it works, that I am not sure). > > I think using `/en/stable/` (or /latest) as the default URL redirect is the > thing — as a new release gets promoted, google/etc will keep using/crawling > that, and that link doesn't change. > > I think the robots thing would need something a bit like: > > allow: /en/stable/ > disallow: /en/ > > Though in principle, no-index would be preferable to "do not crawl". Not sure > what levers RTD has in that regard, if /stable/ and /9.4/ are actually > different sets of html files then adding in an HTML tag for noindex > might be simple enough for !=stable ? > > Rob :) > ___ > gdal-dev mailing list > gdal-dev@lists.osgeo.org > https://lists.osgeo.org/mailman/listinfo/gdal-dev ___ gdal-dev mailing list gdal-dev@lists.osgeo.org https://lists.osgeo.org/mailman/listinfo/gdal-dev
Re: [gdal-dev] Building GDAL documentation with ReadTheDocs
> 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
wrote:
>
> Daniel Baston via gdal-dev 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=jsonp=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=latest_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
___
gdal-dev mailing list
gdal-dev@lists.osgeo.org
https://lists.osgeo.org/mailman/listinfo/gdal-dev
[gdal-dev] Building GDAL documentation with ReadTheDocs
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. Thanks, Dan ___ gdal-dev mailing list gdal-dev@lists.osgeo.org https://lists.osgeo.org/mailman/listinfo/gdal-dev
Re: [gdal-dev] OGR SQL CAST geometry example
If a single MULTIPOINT record is OK, then you can do ogrinfo test.shp -q -dialect SQLITE -sql 'SELECT ST_DissolvePoints(GEOMETRY) FROM test' Dan On Thu, May 30, 2024 at 8:49 PM Dan Jacobson via gdal-dev wrote: > > $ ogrinfo 0.lines.kml -q -dialect SQLITE -sql \ > 'SELECT ST_PointN(GEOMETRY, generate_series(1, ST_NPoints(GEOMETRY))) FROM > "0"' > ERROR 1: In ExecuteSQL(): sqlite3_prepare_v2( > no such function: generate_series > ___ > gdal-dev mailing list > gdal-dev@lists.osgeo.org > https://lists.osgeo.org/mailman/listinfo/gdal-dev ___ gdal-dev mailing list gdal-dev@lists.osgeo.org https://lists.osgeo.org/mailman/listinfo/gdal-dev
Re: [gdal-dev] Doxygen Arguments
It looks like Doxygen is using argument names from the function prototype instead of the implementation: https://github.com/OSGeo/gdal/blob/master/gcore/gdal_priv.h#L753 I did some searching but didn't come across a way to change this behavior. It looks like many other functions include the argument names in the prototype, so maybe RasterIO should be updated to include them too? Dan On Thu, May 9, 2024 at 9:20 AM Andrew Bell via gdal-dev < gdal-dev@lists.osgeo.org> wrote: > Hi, > > I'm looking at the documentation for GDALRasterBand::RasterIO and it's > surprising that the names of the arguments aren't included in the function > prototype despite them being in the doxygen function definition. The > arguments are described well below the function prototype, making it hard > to match things up and you have to assume that the order matches. > > Does some doxygen expert know how the argument names could somehow be > included in the function prototype? > > Web page: > https://gdal.org/api/gdalrasterband_cpp.html#classGDALRasterBand_1a75d4af97b3436a4e79d9759eedf89af4 > > Source: https://fossies.org/linux/gdal/gcore/gdalrasterband.cpp (line 110) > > -- > Andrew Bell > andrew.bell...@gmail.com > ___ > gdal-dev mailing list > gdal-dev@lists.osgeo.org > https://lists.osgeo.org/mailman/listinfo/gdal-dev > ___ gdal-dev mailing list gdal-dev@lists.osgeo.org https://lists.osgeo.org/mailman/listinfo/gdal-dev
Re: [gdal-dev] About -oo -lco -dsco in docs
Perhaps a Sphinx substitution could be made with the relevant text and added to https://github.com/OSGeo/gdal/blob/master/doc/source/substitutions.rst Dan On Wed, Mar 27, 2024 at 5:01 PM Even Rouault via gdal-dev < gdal-dev@lists.osgeo.org> wrote: > Salut Thomas, > > There's a tension between being clear to users, and also aiming at being > concise / not repeating us too much (we have already one thousand pages > of doc to maintain), and if we need to repeat, find the technical way of > doing it without actually having to copy the same text. > > Probably a solution could be to have under each "Open options" > paragraph, and introduction sentence like > > "Consult :ref:`how to specify open options ` with command > line utilities and the API." that links to a page explaining the concept > and how to use it. > > I was wondering if we'd just want to copy that sentence at all > relevant places, or create a custom Sphinx extension for a directive > that would do that. The later is probably overkill. Possibly a one-time > simple Python script could automatically insert that at relevant places > > Even > > > Le 26/03/2024 à 21:25, Thomas Gratier via gdal-dev a écrit : > > Hi, > > > > There are implicit rules when you read the OGR/GDAL docs in fact, in > > particular when you use `ogr2ogr` or `ogrinfo` > > > > `-oo =` like "Open Options" > > `-lco =` for "Layer Creation Option" > > `-dsco =` for "DataSet Creation Option" > > > > So, when you read for instance > > https://gdal.org/drivers/vector/csv.html, you will see there is a > > section "Open options" so you will know that you can use `-oo`. Also, > > you will see a "Layer Creation options" block so again, you will know > > it mean use `-lco`. > > > > It's documented in "ogr2ogr" but you need to know the rule to make the > > link in your mind when reading the doc. Any idea to clarify the doc > > about the "tip". > > > > An idea could be about adding in drivers docs "Open options" block a > > sentence like "When using the command line, use the flag `-oo > > =`" and do the same for "Layer creation options" block > > "When using the command line, use the flag `-lco =`" > > > > Thoughts about the suggestion? Better idea? Not worth? > > > > Regards, > > > > Thomas Gratier > > > > ___ > > gdal-dev mailing list > > gdal-dev@lists.osgeo.org > > https://lists.osgeo.org/mailman/listinfo/gdal-dev > > -- > http://www.spatialys.com > My software is free, but my time generally not. > > ___ > gdal-dev mailing list > gdal-dev@lists.osgeo.org > https://lists.osgeo.org/mailman/listinfo/gdal-dev > ___ gdal-dev mailing list gdal-dev@lists.osgeo.org https://lists.osgeo.org/mailman/listinfo/gdal-dev
