Can't get Mkdocstrings to understand Numpy docstrings

[ldouteau]

Hi, Sorry if that's not a bug, i filed it here because i liked the issue format.

Description of the bug

Setting Mkdocstring to use Numpy docstrings has no effect.

I tried to configure Mkdocstrings following the guidelines in the doc, but the API doc remains formatted nicely for Google docstrings and not for Numpy ones. I tried several configurations, but from what i observed setting docstring_style had no effect.

To Reproduce

• Install Mkdocstrings for Python

  pip install mkdocs mkdocstrings[python]

• define a module mymod.py that has 2 functions, with docstrings using respectively Google-format & Numpy format.

  def google_docstrings(a: float, n: int = 0) -> str:
      """_summary_
  
      Args:
          a (float): _description_
          n (int, optional): _description_. Defaults to 0.
  
      Returns:
          str: _description_
      """
      return f"{round(a, n)}"
  
  def numpy_docstrings(a: float, n: int = 0) -> str:
      """_summary_
  
      Parameters
      ----------
      a : float
          _description_
      n : int, optional
          _description_, by default 0
  
      Returns
      -------
      str
          _description_
      """
      return f"{round(a, n)}"
  

• Initialize mkdocs with mkdocs new .

• Use a basic index.md

  # Welcome to MkDocs
  
  For full documentation visit [mkdocs.org](https://www.mkdocs.org).
  
  ## API
  
  ::: mymod
  

• Configure mkdocs.yml to use Numpy docstrings

  site_name: My Docs
  nav:
    - Home: index.md
  plugins:
    - search
    - mkdocstrings:
        handlers:
          python:
            paths: [.]
            options:
              docstring_options:
                docstring_style: numpy
  

• Run mkdocs serve

I get the following:

Full traceback

No error logs showing up, Mkdocs runs smoothly

Expected behavior

Setting docstring_style to numpy should format nicely the function documented with Numpy docstrings.

Setting docstring_style to google should format nicely the function documented with Google docstrings (Works currently).

I would love automatic detection of docstring format (for heterogeneous codebases) but i would understand if this were too complex to setup.

Environment information

python -m mkdocstrings.debug  # | xclip -selection clipboard

• System: Windows-11-10.0.22631-SP0
• Python: cpython 3.12.2
• Environment variables:
• Installed packages:
  • mkdocstrings v0.25.1

Additional context

[pawamoy]

Hi @ldouteau, sorry for the late answer. It looks like you just need to dedent docstring_style once.

[ldouteau]

Thanks for your answer, that fixed it !