[ENHANCEMENT] Language Server: Python Keyword Docstring Hover Format

[martinezlc99]

When using the vscode extension and hovering over a keyword defined in Python, the documentation displayed when hovering over the keyword is unformatted. For example, for the keyword below:

# keyword.py

def example_keyword_1(input_1: str, input_2: int, input_3: bool) -> None:
    """This is an example keyword used for comparing doc string formats

    :param input_1: This is input 1
    :param input_2: This is input 2
    :param input_3: This is input 3
    """

    print(f"input 1: {input_1} input 2: {input_2} input 3: {input_3}")

which renders as:

.

Its seems only markdown is supported.

Proposed Solution
The docstring should be rendered based on the docstring format (reST, Google or Numpy). Instead of having robotcode try to guess the format, using the libdoc.doc-format setting defined in robot.toml

Alternatives Considered
We can write the Python docstrings in markdown, but this then has consequences for other tooling for Python.

Additional Context
I was unable to find if this an configuration option already defined. I tried using the libdoc.doc-format in robot.toml, but it didn't appear to work.

I am also glad to submit a PR for this as well.

[martinezlc99]

@d-biehl - sorry to bump this but we are very interested in your opinion...mainly to determine if this is correctly diagnosed as an enhancement. Glad to move this issue to a discussion or start another conversation there.

[d-biehl]

Hey!

RobotCode can only display the documentation formats that Robot Framework itself supports. Since Robot Framework doesn't recognize Google-Style or NumPy-Style docstrings, RobotCode can't display them in formatted form either.

---

Supported Formats

Robot Framework currently only recognizes these documentation formats:

• ROBOT (Default – simple structured syntax, works without additional dependencies)
• HTML
• TEXT
• reST (requires docutils

Google and NumPy styles are unfortunately not supported.

---

How it Works

You define the format directly in your library:

ROBOT_LIBRARY_DOC_FORMAT = "ROBOT"  # Recommended - works without dependencies
# or
ROBOT_LIBRARY_DOC_FORMAT = "reST"   # Requires docutils

The ROBOT format is usually the best choice since it works without additional dependencies and still provides good formatting. With reST and docutils you get slightly more formatting options.

You can find more details in the Robot Framework Documentation.

Important: The libdoc.doc-format setting in robot.toml won't help you here – that only affects the libdoc output when you use the tool on the console. RobotCode follows the library's ROBOT_LIBRARY_DOC_FORMAT.

---

How RobotCode Works

RobotCode generates documentation based on your library's ROBOT_LIBRARY_DOC_FORMAT and internally uses the libdoc tool. In the end, the output is processed as Markdown for VS Code (VS Code only supports Markdown with selected support for HTML tags). This happens in the to_markdown method that you found.

• ROBOT format: RobotCode formats the docstrings accordingly. This is simple since the ROBOT format is similar to Markdown and doesn't require additional dependencies.
• reST format: Also works, provided you have docutils installed. Here there might be issues due to VS Code's limitations, since reST is more complex. It essentially mixes Markdown with embedded HTML tags, but not all HTML tags are supported by VS Code.
• HTML and TEXT: Are simply attempted to be displayed as Markdown without further adjustments.

---

Outlook

Markdown support for Robot Framework is already planned! There's a Feature Request (#5304) in the milestone for version 7.4. The Robot Framework documentation is also being ported to Markdown – there are already corresponding discussions in Slack and corresponding repositories (just can't find the link right now).

---

Your Options

1. Recommended: Convert docstrings to ROBOT format – works without dependencies, is simple and readable. However, it's not a Python standard, but in Resource files and Robot Test Suites only the ROBOT format is supported.
2. Alternative: Use reST if you need more complex formatting (but requires docutils)
3. Feature Request: Request Google/NumPy-Style support directly in the Robot Framework Repository

The ROBOT format is completely sufficient for most cases and you don't need to install additional packages.

---

Documentation:

• https://robotframework.org/robotframework/latest/RobotFrameworkUserGuide.html#documenting-libraries
• https://robotframework.org/robotframework/latest/RobotFrameworkUserGuide.html#documentation-format
• https://robotframework.org/robotframework/latest/RobotFrameworkUserGuide.html#documentation-formatting

---

A major problem in the Python world is indeed the variety of documentation formats. Robot Framework deliberately supports only the above formats (and later Markdown as well) – this is a pragmatic decision for better compatibility, fewer dependencies, and a better user experience.

RobotCode will therefore not provide support for Google-Style or NumPy-Style docstrings, unless Robot Framework itself implements this in the future.

Is this sufficient as a foundation for further discussion, or are there still open questions?

[martinezlc99]

@d-biehl - thank you for the very detailed response! I am fairly sure we tried the setting the ROBOT_LIBRARY_DOC_FORMAT to "reST" but not sure if we had the docutils package installed.

Again, thanks for the detailed response.