Numpy Docstrings look bad, how can I improve it?

[nh916]

I am generating documentation from docstrings. I've tried both Google style docstrings and Numpy style. I noticed that the Google Style docstrings looks significantly better and has all the nice widgets where as the numpy documentation looks bad. Is there any way that I can mess with the configuration to make it look a lot better? Do I have my configurations wrong?

I am using material MKDocs

MKDocs.yaml Configurations

plugins:
  - search
  - mkdocstrings:
      default_handler: python
      handlers:
        python:
          paths: [src, docs]
          options:
            show_bases: true
            show_source: true
            docstring_style: numpy
      watch:
        - src/

markdown_extensions:
  - toc:
      baselevel: 2
      permalink: True
  - attr_list
  - md_in_html
  - admonition
  - pymdownx.details
  - pymdownx.superfences
  - pymdownx.inlinehilite
  - pymdownx.snippets
  - pymdownx.critic
  - pymdownx.caret
  - pymdownx.keys
  - pymdownx.mark
  - pymdownx.tilde
  - pymdownx.tabbed:
      alternate_style: true
  - pymdownx.highlight:
      anchor_linenums: true
  - pymdownx.emoji:
      emoji_index: !!python/name:materialx.emoji.twemoji
      emoji_generator: !!python/name:materialx.emoji.to_svg

[pawamoy]

Hello!

the numpy documentation looks bad

Unfortunately this is very subjective and I cannot know what you see and what you expect instead. Please share some code and screenshots that replicate the issue so that I can provide some help.

[nh916]

that makes sense.

Google Configuration

Screenshot

MKDocs.yaml configuration

plugins:
  - search
  - mkdocstrings:
      default_handler: python
      handlers:
        python:
          paths: [src, docs]
          options:
            show_bases: true
            show_source: true
            docstring_style: google
      watch:
        - src/

Google Docstrings

    @property
    def source(self) -> str:
        """
        The File node source can be set to be either a path to a local file on disk
        or a URL path to a file on the web.

        Example:
            URL File Source
            ```python
            url_source = "https://wikipedia.com"
            my_file.source = url_source
            ```

            Local File Path
            ```python
            my_file.source = "/home/user/project/my_file.csv"
            ```

        Returns:
            source: str
                A string representing the file source.
        """

---

Numpy Configuration

Screenshot

MKDocs.yaml

plugins:
  - search
  - mkdocstrings:
      default_handler: python
      handlers:
        python:
          paths: [src, docs]
          options:
            show_bases: true
            show_source: true
            docstring_style: numpy
      watch:
        - src/

Numpy Docstrings

    @property
    def source(self) -> str:
        """
        The File node source can be set to be either a path to a local file on disk
        or a URL path to a file on the web.

        Example
        --------
        URL File Source
        ```python
        url_source = "https://wikipedia.com"
        my_file.source = url_source
        ```

        Local File Path
        ```python
        my_file.source = "/home/user/project/my_file.csv"
        ```

        Returns
        -------
        source: str
            A string representing the file source.
        """

[pawamoy]

Thanks a lot, that's what I needed to see.

So, the only difference I see is that Google docstrings support arbitrary admonitions (in this case: Example), while Numpy docstrings do not. If you look at the table of supported sections per style, you'll see that both style expect "Examples" (plural). With the Google-style, "Example" (singular) falls back to being parsed as an admonition. With the Numpy style, which does not support arbitrary admonitions, it falls back as being parsed as a text block, which is then rendered as Markdown, and therefore as a heading (hence the small, grey "Example" heading in your screenshot).

We're open to adding support for arbitrary admonitions with the Numpy style. You can try to send a PR, or I'll eventually get to it 🙂

[nh916]

thank you so much that helps a lot.

I tried putting it as Examples but I am still not getting the admitions

Screenshot

    @property
    def source(self) -> str:
        """
        The File node source can be set to be either a path to a local file on disk
        or a URL path to a file on the web.

        Examples
        --------
        URL File Source
        ```python
        url_source = "https://wikipedia.com"
        my_file.source = url_source
        ```

        Local File Path
        ```python
        my_file.source = "/home/user/project/my_file.csv"
        ```

        Returns
        -------
        source: str
            A string representing the file source.
        """

am I doing something wrong?

[pawamoy]

It's expected: Examples (plural) is recognized as a docstring section. The only benefit is that pycon syntax is recognized in such sections, without triple backticks fences:

Examples:
    >>> print("no need for ```")

[nh916]

I thought this was Google style where it is indented with a colon

Examples:
    >>> print("no need for ```")

and this was Numpy style where it is underlined

        Examples
        --------
        URL File Source
        ```python
        url_source = "https://wikipedia.com"
        my_file.source = url_source
        ```

am I doing the markdown wrong?

[pawamoy]

For a Numpystyle docstring that would be:

Examples
--------
>>> print("something")

[nh916]

For a Numpystyle docstring that would be:

Examples
--------
>>> print("something")

got it!
I'll try that!

Thank you!