search

executablebooks / sphinx-panels

A sphinx extension for creating panels in a grid layout
https://sphinx-panels.readthedocs.io
MIT License
83 stars 20 forks source link

👌 IMPROVE: allow to specify a custom reference role for link-button #58

Open jorisvandenbossche opened 3 years ago

jorisvandenbossche commented 3 years ago

While trying to use sphinx-panels for the pandas docs (finally .. ;)), I ran into an issue with the link-button: because it's hardcoded to use an "any" role, this can give ambiguous targets ("WARNING: more than one target found for 'any' cross-reference ..."). While in actual rst, you could use :ref:`target` or :doc:`target` or :func:`target`, .. to be more specific.

So I think it would be nice if it would be possible for link-button directive to support this as well. There is already a :type: keyword (which now takes "url" or "ref"), which could be used for this. The only problem is that for backwards compatibility, "ref" should keep meaning "any", and not actually "ref". It also seems that sphinx automatically changes "ref" into "std:ref" (or this might depend on your settings, though?), and specifying "ref" as the reftype without a domain gives errors in sphinx. So you have to use "std:ref" as a user, unfortunately (unless there is a sphinx function we can use to resolve those).

I directly made a PR instead of an issue because I was trying it out anyway if it could work, and the diff might make my question/suggestion more concrete. If there is interest in this, I can further clean-up the PR (and add tests, etc).

welcome[bot] commented 3 years ago

Thanks for submitting your first pull request! You are awesome! :hugs:
If you haven't done so already, check out EBP's Code of Conduct and our Contributing Guide, as this will greatly help the review process.
Welcome to the EBP community! :tada:

chrisjsewell commented 3 years ago

Thanks @jorisvandenbossche yes sounds reasonable 👍 I'll have a think about the issues you mention and get back to you (feel free to ping me if I forget lol)