Skip to content

Doc: Fix gpkg option links#14729

Open
geographika wants to merge 2 commits into
OSGeo:masterfrom
geographika:rst-options
Open

Doc: Fix gpkg option links#14729
geographika wants to merge 2 commits into
OSGeo:masterfrom
geographika:rst-options

Conversation

@geographika
Copy link
Copy Markdown
Collaborator

Fixes #10218 by simply copying the options from the SQLite page so the :ref:s point to the correct location.

I tried (and failed) to update the copy-config directive to allow for links on the same page. The refs are already resolved pointing to anchors on the the page they are first declared, when copied in https://github.com/OSGeo/gdal/blame/cb541139e8c4a6fdf267fff69b9fd57ee2c373fa/doc/source/_extensions/configoptions.py#L165 so maybe the original RST should be stored and inserted instead. The caching in the function also probably needs to be ignored in some cases.

Just to note, this is only an issue for :ref: in a config:: which points to a link on the same page, and is then used in :copy-config:. There are no other cases of this currently in the docs apart from the 2 fixed here, so there is probably little value in spending any more time on this.

If the :ref: points to a different page (and is used in :copy-config: (e.g. in the case of `SQLITE_USE_OGR_VFS also on the gpkg.rst page) then there is no issue.

# works fine in - :copy-config:`SQLITE_USE_OGR_VFS`

- .. config:: SQLITE_USE_OGR_VFS
     :choices: YES, NO

     YES enables extra buffering/caching
     by the GDAL/OGR I/O layer and can speed up I/O. More information
     :ref:`here <vsicached>`.
     Be aware that no file locking will occur if this option is activated, so
     concurrent edits may lead to database corruption.

@rouault rouault added the backport release/3.13 Backport to release/3.13 label Jun 6, 2026
@geographika
Copy link
Copy Markdown
Collaborator Author

I spoke too soon about a simple fix - this causes:

1: /__w/gdal/gdal/doc/source/drivers/vector/gpkg.rst:556: WARNING: Duplicate definition of OGR_SQLITE_CACHE (previously defined at drivers/vector/sqlite:494)
1: /__w/gdal/gdal/doc/source/drivers/vector/gpkg.rst:560: WARNING: Duplicate definition of OGR_SQLITE_SYNCHRONOUS (previously defined at drivers/vector/sqlite:498)

Switching to an include instead.

@geographika
Copy link
Copy Markdown
Collaborator Author

Includes don't work as the :config:s are unique keys.
Best I could do is move the :ref: to another block and duplicate on each page, while adding a short description. Links now work, and looks as follows (slightly strange spacing):

image

- .. config:: OGR_SQLITE_CACHE

see :ref:`Performance hints <target_drivers_vector_sqlite_performance_hints>`.
increases SQLite’s internal page cache (in MB).
Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

short description to also put in gpkg.rst?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

backport release/3.13 Backport to release/3.13

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Doc: gpkg "Performance Hints" link broken

2 participants