search

pypa / readme_renderer

Safely render long_description/README files in Warehouse
Apache License 2.0
158 stars 89 forks source link

Error: Unknown interpreted text role "kbd". #148

Closed ghost closed 1 year ago

ghost commented 5 years ago

Describe the bug

:kbd: in rst file is not recognized by pypi

Expected behavior

:kbd: in rst file should be recognized by pypi To Reproduce

Additional context ":kbd:" in rst files is supported by Gitlab, Github, readthedocs, etc. However I've noticed that restview does not support it.

McSinyx commented 4 years ago

I stumbled upon this when flit refuses to build when README.rst uses the kbd role. I took a deeper look and it seems that the proposal for this over docutils (which readme_renderer uses to render, ehm, READMEs) has yet to be accepted.

I suppose we can either use Sphinx as the reST backend for readme_renderer or to document about the lack of support the kbd role on PyPI. Personally I'm fine without these solutions though.

miketheman commented 2 years ago

Looks like docutils added kbd in 0.17 https://docutils.sourceforge.io/HISTORY.html#release-0-17-2021-04-03

The support appears to be part of the HTML5 writer, so it’s worth testing the behavior today or whether this relies on updating our writer to use html5 as well. #249

miketheman commented 2 years ago

Looks like I was incorrect in my assertion about html5 - it's already supported today, with a little extra effort.

The current readme_renderer will support the kbd role if you declare a custom role in your rst, per the current docutils behavior. Example:

My Package
==========

.. role:: kbd

Type :kbd:`Ctrl+C` to quit

will output this HTML:

<p>Type <span class="kbd">Ctrl+C</span> to quit.</p>

And the current Warehouse CSS should pick that up and render as code.

TL,DR: It looks like all you'd have to do is add .. role:: kbd in your RST for this to work.

miketheman commented 1 year ago

Closing, as there's no action for us to take here right now.