Skip to content

Conversation

@sbesson
Copy link
Member

@sbesson sbesson commented Dec 18, 2025

Fixes #2434

See https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-primary_domain and https://www.sphinx-doc.org/en/master/usage/domains/index.html

The definition of a custom property cross-reference clashes with the directive defined in the Python domain which is the default domain. To fix the usage without updating all references, this changes the default domain to rst and updates all directives, roles and references specific to the Python domain in the table documentation page to use the py namespace

The definition of the custom property cross-reference is also amended to use an indextemplate value consistent with the reference documentation

In terms of testing:

@sbesson sbesson marked this pull request as draft December 18, 2025 22:16
See https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-primary_domain
and https://www.sphinx-doc.org/en/master/usage/domains/index.html

The definition of a custom property cross-reference clashes with the
directive defined in the Python domain which is the default domain.
To fix the usage without updating all references, this changes the
default domain to rst and updates all directives, roles and references
specific to the Python domain in the table documentation page to use
the py namespace

The definition of the custom property cross-reference is also amended
to use an indextemplate value consistent with the reference
documentation
@sbesson sbesson changed the title Use pair: %s; property as the indextemplate of the property cross-ref Switch default domain to the reStructuredText domain Dec 19, 2025
@sbesson sbesson marked this pull request as ready for review December 19, 2025 09:17
@sbesson sbesson requested a review from pwalczysko December 19, 2025 09:21
@pwalczysko
Copy link
Member

In terms of testing:

* check there are no changes to the configuration properties page i.e. https://omero--2508.org.readthedocs.build/en/2508/sysadmins/config.html vs https://omero.readthedocs.io/en/stable/sysadmins/config.html

* check the pages with references to OMERO configuration properties now link back to the configuration section e.g. https://omero--2508.org.readthedocs.build/en/2508/sysadmins/server-ldap.html vs https://omero.readthedocs.io/en/stable/sysadmins/server-ldap.html

* check the rendering/links in the OMERO.tables page is unaffected https://omero.readthedocs.io/en/stable/developers/Tables.html#omero.grid.Table vs https://omero--2508.org.readthedocs.build/en/2508/developers/Tables.html#omero.grid.Table

Test 1: (changes in the configureation properties page):

  • Click on the View page source on the two highlighted links and copy the content into two files (2805pr and stable)
  • Run diff on those two files
  • No changes detected -> pass

Test 2: (references to OMERO configuration properties now link back to the configuration section)

Test 3: (check the rendering/links in the OMERO.tables page)

  • Check optically the htmls -> layout of complex Notes with code, links on the page and internal anchors behaviour
  • Note there are no differences between the 2508 and the stable htmls -> pass

Copy link
Member

@pwalczysko pwalczysko left a comment

Choose a reason for hiding this comment

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

Based on testing in #2508 (comment) lgtm. Thank you.

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

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Missing cross-references for OMERO properties

2 participants