leonhard-s/python-sphinx-highlighter

An extension for VS Code that highlights Sphinx directives and references in Python docstrings.

Python Sphinx Highlighter

This is an extension for Visual Studio Code designed to improve readability of Python docstrings using the Sphinx docstring format.

Features

The source code shown is the example from the Read the Docs Sphinx docstring format introduction.

Sphinx docstrings are compact and can easily be converted into HTML or PDF documentation using Sphinx and its Autodoc extension, but are generally harder to work with in the source code.

This extension alleviates this drawback by highlighting select Sphinx and reStructuredText directives within Python docstrings.

Compatibility Notes

This extension is only compatible with the default VS Code Python extension. It is not compatible with Python for VSCode, see #6 for details.

Release Notes

v0.3.0

Changes

• Multi-word tag values (such as :param int y:) are now permitted. This is used by Sphinx autodoc to include the argument type in a single line:

  def foo(x, y):
      """
      :param int x: Argument with autodoc shorthand
  
      :param y: Argument with separate type tag
      :type y: int
      """
      ...

  Both variants are correct and highlighted when using this extension.

Bug fixes

• Single character tag values (such as :param x:) are now recognized as tags

v0.2.0

Changes

• The value portion of a named tag (such as :param arg:) is now selectable individually via the entity.name.tag.value.sphinx scope (#7)

Bug fixes

• The closing colon of a Sphinx tag will now be correctly scoped as punctuation.definition.interpreted.sphinx (#8)

v0.1.1

Bug fixes

• Parameters ending in numbers will now be highlighted properly (#4)
• Fixed parameters using wildcard notation (*args, **kwargs) not being recognized as sphinx tags (#4)
• Inline formatting will no longer be applied when the control characters are surrounded by whitespace (#5)

v0.1.0

Initial release

python-sphinx-highlighter's Issues

Support inline generic types

While basic types are supported for inline argument typing (:arg str name:), the RegEx does not allow nested types or generics like :arg list[str] sources:.

Numpy style docstring issues

The following is a collection of issues with Numpy style docstrings compiled after inspection of the Napoleon plugin's example code.

Note: This example is not an exhaustive description of the Numpy docstring standard. Once the other issues are (mostly) resolved, refer to the numpydoc docstring guide for more examples.

---

• Section headings are not highlighted.

• Parameter type hints are not highlighted.

All other issues are currently related to or identical to ones listed in issues #1 and #2.

Apply VSCode reST highlighting to Pyhton docstring.

Hi, I came across your extension and basically highlighting the docstring for sphinx is quite smart. Unfortunately in version 0.3.0 the highlighting breaks out and also highlights native python code like var = 'this is my string with :anything: sphinx-like substing' - highlights anything, which is not desired I think. :D

However, I am wondering why you are not simply applying the VSCode highlighter inside of reST Python docstrings. Keeping the theme's text color and using the builtin grammar of VSCode for highlighting. I've seen this mechanism already in some extensions (i.e for code-block highlighting), but I cannot remember which one it was.

Isn't it possible to use VSCode to detect tripple-quote docstrings as it is also defined as textMate scope string.quoted.docstring.multi.python? And then switch to the reST highlighter inside this docstring? Wouldn't this be much easier and more complete?

Hope that helps. Cheers.

support for multiple docstring formats

Hi there,

I was looking for this exact extension, I find it quite crazy that it is not more a desired use case, it seems so logical to have more readable docstrings. One thing though, on my projects I use the google format, so it would be amazing if this extension could be configured to use those.

I might try to set that up if no one else has time for it.

Cheers !

Differentiate between tag and valuie

Problem

I'm porting Darcula theme from PyCharm and trying to achieve same look for docstrings.

Your extension works like a charm, however it doesn't differentiate between tag and its value, making it impossible to replicate PyCharm look, or do other customisations (e.g. highlight only param value, or highlight it s source):

PyCharm	VSCode

Details

My current json settings:

        {
            "scope": [
                "entity.name.tag.sphinx",
                "punctuation.definition.interpreted.sphinx"
            ],
            "settings": {
                "foreground": "#629755",
                "fontStyle": "italic bold underline"
            }
        },

Inspector:

Proposal

Introduce separate scope for tag value, e.g. entity.name.tag.value

Thank you for the awesome extension!

Sphinx style docstring issues

The following is a collection of issues with Sphinx style docstrings compiled after inspection of the example code provided in the Sphinx RTD tutorial.

---

• The example uses single backticks for reference to variables. Currently, only substrings enclosed by double backticks are highlighted as code blocks.

  Should these be treated the same as code blocks? Differently? ``var`` could be used to refer to generic literal blocks, with `var` being reserved for variables and names that are defined in the current scope.

The default Sphinx behaviour is to assign these names the default interpreted text role. For the purposes of this extension, highlighting them as literals is therefore not appropriate.

Google style docstring issues

The following is a collection of issues with Google style docstrings compiled after inspection of the Napoleon plugin's example code.

---

• Literal raw blocks defined with two trailing colons are busted again. They used to work, so this is likely just a typo or omission.

• The bold formatting used for section headings breaks when the previous code block indented by more than two levels just before.

  This is likely due to the previous indented block not finishing properly, which results in the next section's header being consumed by the previous block. Inserting any character to make the indentation a gapless "staircase" again fixes it.

• Module-level variable and attribute annotations currently do not have any type highlighting.

• Emphasis control characters are currently applied within code blocks, as well as if the corresponding asterisk is escaped.

• Parameter highlighting breaks if type information is provided: param1 (int): The first parameter.

  Note that it is also permitted to use cross-references for these type hints: param2 (:obj:`str`, optional): The second parameter

• Magic method names are treated as links and underlined - this is fine as long as this can be escaped, which is not a thing yet (see above).

• Currently, single words ending in a colon that happen to fold into a new line are treated as headings. This can likely be addressed by requiring a blank line lookbehind in the corresponding RegEx.

Closing `:` is not reported as `punctuation.definition.interpreted.sphinx`

In source code, I see that tag: meant to have 3 groups, however for some reason third (closing :) is not reported as a sphinx scope:

  tag:
    # RST inline tags. These are mostly used for autodoc tags, i.e.
    # things like ":param key:" or ":rtype: str".
    match: (:)(${{ alpha }}[${{ alphaNum }} _\-\.\*\\]+?${{ alphaNum }}(\?_)?)(:)(?!`)
    captures:
      1: { name: punctuation.definition.interpreted.sphinx }
      2: { name: entity.name.tag.sphinx }
      3: { name: punctuation.definition.interpreted.sphinx }

Do not allow whitespaces around inline formatting control characters

Text is currently highlighted as bold or italic even if the formatting characters are surrounded by whitespace. This causes issues when using these characters for applications other than inline text formatting.

For example, the QGIS Python libraries use the following headers for their source files, which are incorrectly treated as italics:

Support three-field tags

Sphinx allows specifying single-word types as part of the :param <field>: block:

:param str name: A field called `name` of type ``str``.

This is currently not highlighted correctly.

Make parameter highlighting rules more permissive

Many parameters end in numbers (p1, etc.). These are currently not picked up by the highlighting RegEx (see below).

Update:

Parameters using wildcard notation (*args, **kwargs) must be escaped for Sphinx to properly parse them. These escapes are currently not recognized by the highlighting rules.

Documentation for how to use the extension is unclear

Hi I just installed this extension, but I don't know how to enable Sphinx Highlight. I am using the Pylance language Server.