[issue44084] Can't mark match, case, _ as keywords in docs

[Tal Einat]

Change by Tal Einat :


--
resolution:  -> not a bug
stage:  -> resolved
status: open -> closed

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue44084] Can't mark match, case, _ as keywords in docs

[Tal Einat]

Tal Einat  added the comment:

Thanks Dominic, it seems that you're absolutely right!

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue44084] Can't mark match, case, _ as keywords in docs

[Dominic Davis-Foster]

Dominic Davis-Foster  added the comment:

I'm not sure this is a Pygments or Sphinx bug. The documentation for the 
:keyword: role[1] says:

   This creates a link to a reference label with that name, if it exists.


Looking at the documentation source for "Compound statements"[2] each section 
for a particular keyword is preceded by a reference label for the relevant 
keyword(s).

So for "match" and "case" all that's needed is to put the label before the 
section of the docs talking about them.
In fact, it seems that "match" does have a label[3], and I can link to it 
successfully; it's just "case" and "_" that don't work

"_" is more tricky, as you can't have a reference label called that. However, 
if you pick another name for the label (say, "underscore") you can use that as 
the target name and still have "_" as the text like so:

:keyword:`_ `


[1] 
https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#role-keyword
[2] 
https://raw.githubusercontent.com/python/cpython/main/Doc/reference/compound_stmts.rst
[3] 
https://github.com/python/cpython/blame/main/Doc/reference/compound_stmts.rst#L514

--
nosy: +dom1310df

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue44084] Can't mark match, case, _ as keywords in docs

[Tal Einat]

New submission from Tal Einat :

Beginning in Python 3.10, `match`, `case` and `_` are "soft keywords", i.e. 
they are considered keywords only in specific parts of the syntax.

However, they cannot be tagged with a :keyword:`...` role in our docs.

This appears to be due to not appearing in the list of keywords in the Python 
lexer in Pygments, which is used by Sphinx.

I've opened an issue on the Pygments repo about this:
https://github.com/pygments/pygments/issues/1797

--
assignee: docs@python
components: Documentation
messages: 393301
nosy: docs@python, taleinat
priority: normal
severity: normal
status: open
title: Can't mark match, case, _ as keywords in docs
type: behavior
versions: Python 3.10, Python 3.11

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com