[gdal-dev] Doc: driver + config options summary pages [was Re: How to know which formats allow editing with ogrinfo?]

[Eli Adam]

On Sat, Nov 16, 2019 at 9:12 AM Even Rouault <even.rouault at spatialys.com> wrote:
>
> > > If so, then yes if someone contributes it, that'd be welcome. However I
> > > think we'd want it to be generated from a Python script from the
> > > individual .rst pages, by parsing the directives like "..
> > > supports_create::" that are in those .rst files. That way that would make
> > > maintainance of the summary easier (and initial version less tidious that
> > > doing that manually)
>
> OK, so I've added two new directives
>
> .. built_in_by_default::
>
> or
>
> .. build_dependencies:: put here dependencies name
>
> and just used them on a couple drivers for demo:
> https://github.com/OSGeo/gdal/commit/0b3b1ed25bdde6f49a6515e0431d78bc9729ff83
>
> A script that fetches all the information from individual pages
> is run automatically at each documentation build and generates a summary table
> at
> https://gdal.org/drivers/raster/index.html
> https://gdal.org/drivers/vector/index.html
>
> ==> What remains to be done is to go through all driver .rst pages and add
> .. built_in_by_default:: or .. build_dependencies:: where appropriate so that
> no "???" remains
>
> Volunteers ?

If the old table is a reliable source, I can do a good portion of them.

>
> > > Migrating the wiki page to the doc could be useful. My own opinion is that
> > > driver specific configuration options should be documented in the driver
> > > specific page, rather than in a global config option page. Same with /vsi
>
> I've also added a specific role when you use a configuration option
>
> :decl_configoption:`FOO`
>
> Example of use:
>
> https://github.com/OSGeo/gdal/commit/c8fcb6d941c0251219dbd57f701e5b161ce5085e
>
> Similarly to the driver list, a script is run at each build to generate an
> index of declared configuration options (if several pages declare the same
> config option, several links will be created). The result is there:
>
> https://gdal.org/user/configoptions_index.html
>
> ==> What remains to be done is tag appropriately configuration options
> wherever they are already mentionned and add missing ones.
>
> Volunteers ?

I can work on some already mentioned ones.

Thanks for adding this.

Best regards, Eli

>
> Even
>
> --
> Spatialys - Geospatial professional services
> http://www.spatialys.com