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
sphinx.ext.extlinks: option for literal formatting? #11745
Comments
The easiest way is orobably to add a CSS class but that would require doing it for all themes. I think the options approach is better. Unfortunately I don't have time for that :( |
I want to do this, with a menu of choices to include bold/italic/literal. This probably requires changing extlinks to be a dict rather than tuple, though, for readability. The tuple format would be retained but not allow for any formatting or other advanced features. A |
I wrote an extension for composing simple roles (more precisely, it composes the TextElements produced after roles run, if @hugovk doesn't mind using a third-party extension, this issue can be implemented without changing for example, we can compose extensions.append('sphinxnotes.comboroles')
comboroles_roles = {
'cpy-file2': ['literal', 'cpy-file'],
} by using
See https://sphinx.silverrainz.me/comboroles/examples.html#sphinx-ext-extlink for more details. |
@SilverRainZ Thanks for mentioning the extension! If this is coming to Sphinx, then it can wait. My initial plan was to use this for the CPython devguide and PEPs repos, which can use extensions. If we wanted to also use it for CPython itself, then it's better to avoid extensions because we need to make sure the docs build without any for downstream redistributors. |
I'm now thinking this is the best option: it gives theme authors and docs builders the most flexibility to format the extlink in whatever way they want, without being tied to whatever formatting has been implemented in Sphinx. It's also a very small change to Sphinx (two lines of code + two lines of tests) and requires no backwards compatibility concerns around maintaining both tuples and dicts for config. More specifically for CPython, if a Linux distributor builds the docs with an older version of Sphinx, it will still build the docs, they just won't get the CSS class and will get the plain formatting, which I'm not worried about. Please see PR #12319. |
Is your feature request related to a problem? Please describe.
In the Python devguide, we have an extension to add custom roles that add links.
https://github.com/python/devguide/blob/2e9e657b53830806d202df70cbed3353afcdb5d1/_extensions/custom_roles.py
For example,
:cpy-file:`.github/CODEOWNERS`
will expand tohttps://github.com/python/cpython/blob/main/.github/CODEOWNERS
:https://devguide.python.org/core-developers/experts/
This could of course be replaced with
sphinx.ext.extlinks
with this inconf.py
:However, the custom extension output as literal text, and
extlinks
does not apply any formatting and looks like this:Describe the solution you'd like
Add some sort of option to use literal formatting for
extlinks
.This sort of thing adds literal formatting. But it would need some sort of option to enable it:
Describe alternatives you've considered
Keep the extension and custom roles.
Use CSS?
The text was updated successfully, but these errors were encountered: