Documentation for how to use the extension is unclear

[leonhard-s]

Documentation for how to use the extension is unclear

[jeremyvital4]

Thank you for the tip to disable extensions. I figured out the culprit: https://marketplace.visualstudio.com/items?itemName=tht13.python

Not sure why I had this extension in the first place -- it is very old and not used by anyone anymore. I've disabled and removed it. Must have been an artifact of installing the wrong python extension a long time ago. Sphinx highlighting looks great now!!

[leonhard-s]

Hi - this extension should be active immediately. Here are some troubleshooting steps you can try:

1. This extension works by injecting its own highlighting rules into the default Python syntax highlighter. If you have other extensions that do so or are using a different syntax highlighter, they may conflict with this extension (Pylance only injects additional context into the regular highlighter and is fully compatible with this extension).

   To confirm whether this is the case, try disabling all extensions but this one. If this resolves the issue, please let me know what extensions are causing it so I can investigate.

2. The highlighter does not specify the colour used; it can only flag a substring as a certain type of object. Your current editor theme then picks the colours used to represent these objects.

   Some themes work well (such as the GitHub themes of the github.github-vscode-theme extension), others (such as the default "Light (Visual Studio)") happen to use very similar colours for these object types, rendering this extension ineffective.

3. The highlighting rules are quite strict and may contain errors. Below are some docstrings that are known to work with the current version (0.1.1). If these work for you, please share an example of the types of docstrings that are not being detected properly so I may investigate.

Example docstrings

def from_line(cls: Type[_EntityT], line: str, **kwargs: Any) -> _EntityT:
    """Create a new instance from the given line.
    Lines passed into this element must start with the appropriate
    card identifier; trailing whitespace is allowed.
    If any bad data is encountered, a
    :class:`~py2dm.errors.FormatError` should be raised by the
    implementation.
    :param line: The line to parse.
    :type line: :class:`str`
    :return: An instance as described by the provided `line`.
    :rtype: :class:`Entity`
    """


def __init__(self, id_: int, x: float, y: float, z: float) -> None:
    r"""Create a new node.
    .. seealso::
        You can also create new nodes directly through the
        :meth:`py2dm.Writer.node` method.
    :param id\_: The unique D of the node.
    :type id\_: :class:`int`
    :param x: X position of the node.
    :type x: :class:`float`
    :param y: Y position of the node.
    :type y: :class:`float`
    :param z: Z position of the node.
    :type z: :class:`float`
    """
    if x == float('nan') or y == float('nan') or z == float('nan'):
        raise ValueError(f'Invalid node position: ({x}, {y}, {z})')
    self.id: int = id_
    """Unique identifier of the node.
    :type: :class:`int`
    """