Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Sphinx Style Docstring Incorrectly Rendering "Other Parameters" #6100

Open
divenex opened this issue Jul 5, 2024 · 1 comment
Open

Sphinx Style Docstring Incorrectly Rendering "Other Parameters" #6100

divenex opened this issue Jul 5, 2024 · 1 comment
Assignees
Labels
bug Something isn't working docstrings regression

Comments

@divenex
Copy link

divenex commented Jul 5, 2024

Many thanks for this addition @rchiodo!

The Other Parameters section in NumPy dosctrings is not rendered correctly. Here is an illustration from the standard NumPy dosctring example, where the only_seldom_used_keyword parameter is not correctly rendered in bold. Moreover the Other Parameters section should not be indented, same as Parameters or Raises.

def foo(var1, var2, *args, long_var_name="hi", only_seldom_used_keyword=0, **kwargs):
    r"""Summarize the function in one line.

    Several sentences providing an extended description. Refer to
    variables using back-ticks, e.g. `var`.

    Parameters
    ----------
    var1 : array_like
        Array_like means all those objects -- lists, nested lists, etc. --
        that can be converted to an array.  We can also refer to
        variables like `var1`.

    Other Parameters
    ----------------
    only_seldom_used_keyword : int, optional
        Infrequently used parameters can be described under this optional
        section to prevent cluttering the Parameters section.
    **kwargs : dict
        Other infrequently used keyword arguments. Note that all keyword
        arguments appearing after the first parameter specified under the
        Other Parameters section, should also be described under this
        section.
    """

image

@github-actions github-actions bot added the needs repro Issue has not been reproduced yet label Jul 5, 2024
@debonte debonte assigned rchiodo and unassigned debonte Jul 5, 2024
@rchiodo
Copy link
Contributor

rchiodo commented Jul 15, 2024

This was really the new parser not handling some of the default numpy structs correctly. This bit here:

Returns
    -------
    type
        Explanation of anonymous return value of type ``type``.
    describe : type
        Explanation of return value named `describe`.
    out : type
        Explanation of `out`.
    type_without_description

    Other Parameters
    ----------------

The last type_without_description messed things up. I'll have to special case this. You can see it if you load it here:

https://stsewd.dev/tree-sitter-rst/

@rchiodo rchiodo added bug Something isn't working docstrings regression and removed needs repro Issue has not been reproduced yet labels Jul 15, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
bug Something isn't working docstrings regression
Projects
None yet
Development

No branches or pull requests

3 participants