Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

ENH: Create backreferences for default roles #1122

Merged
merged 2 commits into from Apr 4, 2023

Conversation

StefRe
Copy link
Contributor

@StefRe StefRe commented Mar 31, 2023

When adding mini-galleries for API documentation, only the 5 roles func, math, attr, obj and class were taken into consideration. It is, however, common practice to define a default role (e.g. :py:obj:) using the default_role entry in conf.py. This PR enables the creation of backreferences for references without an explicit role if the default role in conf.py is one of the five roles listed above. Note that only the default role definition in conf.py is taken into consideration, i.e. setting the default role using the .. default-role:: directive is not taken into account.

Further, separate titles (Title <link>) and suppressed link creations (!no.link) are handled correctly now.

The project listed in README.rst use the following default roles:

site default role
Sphinx-Gallery, Nilearn, PyStruct, GIMLi, pyRiemann, Astropy,
PySurfer, PyTorch, PyVista, SimPEG, Fury, Optuna,
Auto-sklearn, OpenML-Python, TorchIO, Biotite, Apache TVM, Tonic
- (none)
Scikit-learn literal
scikit-image autolink
MNE-python, Cartopy, PlasmaPy, Radis py:obj
Nestle, SunPy, Matplotlib, NetworkX obj

Projects in the last two rows benefit from this PR as more backreferences/mini-galleries are created, see matplotlib/matplotlib#25595.

This PR comprises two commits:

TST: Refactor test_identify_names2

  • split into two tests for implicit and explicit names
  • avoid repeated testing of first code_str (code_str and expected were
    extended and the complete code_str tested once more)
  • turn into parameterized test for better extensibility

ENH: Allow for default roles when creating backreferences

When adding mini-galleries for API documentation, only the 5 roles
func, math, attr, obj and class were taken into consideration. It is,
however, common practice to define a default role (e.g. :py:obj:) using
the default_role entry in conf.py. This commit enables the creation of
backreferences for references without an explicite role if the default
role in conf.py is one of the five roles listed above.
Please note the only the default role definition in conf.py is taken
into consideration, i.e. setting the default role using the
.. default-role:: directive is not taken into account.

Further, separate titles (Title <link>) and suppressed link creations
(!no.link) are handled correctly now.

@StefRe StefRe changed the title Enh/default role backref ENH: Create backreference for default roles Mar 31, 2023
@StefRe StefRe changed the title ENH: Create backreference for default roles ENH: Create backreferences for default roles Mar 31, 2023
@larsoner
Copy link
Contributor

larsoner commented Apr 3, 2023

Argh sorry @StefRe I created another conflict for you :(

But +1 in general for this idea, makes sense to me!

- split into two tests for implicit and explicit names
- avoid repeated testing of first code_str (code_str and expected were
  extended and the complete code_str tested once more)
- turn into parameterized test for better extensibility
When adding mini-galleries for API documentation, only the 5 roles
func, math, attr, obj and class were taken into consideration. It is,
however, common practice to define a default role (e.g. :py:obj:) using
the default_role entry in conf.py. This commit enables the creation of
backreferences for references without an explicite role if the default
role in conf.py is one of the five roles listed above.
Note the only the default role definition in conf.py is taken
into consideration, i.e. setting the default role using the
.. default-role:: directive is not taken into account.

Further, separate titles (`Title <link>`) and suppressed link creations
(`!no.link`) are handled correctly now.
@StefRe
Copy link
Contributor Author

StefRe commented Apr 3, 2023

no problem @larsoner , just rebased

@larsoner larsoner merged commit 6594ff5 into sphinx-gallery:master Apr 4, 2023
15 checks passed
@larsoner
Copy link
Contributor

larsoner commented Apr 4, 2023

Thanks @StefRe !

@StefRe StefRe deleted the enh/default-role_backref branch April 4, 2023 18:29
clrpackages pushed a commit to clearlinux-pkgs/pypi-sphinx_gallery that referenced this pull request Apr 18, 2023
… to version 0.13.0

v0.13.0
-------

**Implemented enhancements:**

-  ENH: Create backreferences for default roles `#1122 <https://github.com/sphinx-gallery/sphinx-gallery/pull/1122>`__ (`StefRe <https://github.com/StefRe>`__)
-  ENH raise error in check_jupyterlite_conf with unknown key `#1119 <https://github.com/sphinx-gallery/sphinx-gallery/pull/1119>`__ (`lesteve <https://github.com/lesteve>`__)
-  ENH Add functionality to modify Jupyterlite notebooks based on their content `#1113 <https://github.com/sphinx-gallery/sphinx-gallery/pull/1113>`__ (`lesteve <https://github.com/lesteve>`__)
-  ENH: Add support for WebP `#1111 <https://github.com/sphinx-gallery/sphinx-gallery/pull/1111>`__ (`StefRe <https://github.com/StefRe>`__)

**Fixed bugs:**

-  ENH Clean-up code by early initialization of sphinx_gallery_conf `#1120 <https://github.com/sphinx-gallery/sphinx-gallery/pull/1120>`__ (`lesteve <https://github.com/lesteve>`__)
-  FIX JupyterLite button links `#1115 <https://github.com/sphinx-gallery/sphinx-gallery/pull/1115>`__ (`lesteve <https://github.com/lesteve>`__)
-  Fix thumbnail text formatting `#1108 <https://github.com/sphinx-gallery/sphinx-gallery/pull/1108>`__ (`StefRe <https://github.com/StefRe>`__)

(NEWS truncated at 15 lines)
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet

2 participants