numpy-style broken on class docstring

[mmngreco]

Describe the bug

I'm working on to generate the documentation for my library ineqpy which use numpydoc as docstring-format. When I run the command mkdocs build fails with the following traceback (which is hard to debug):

IneqPy docs/add-mkdocs* (15:15|77s) $ pipenv run mkdocs build && pipenv run mkdocs serve
INFO     -  Cleaning site directory
INFO     -  Building documentation to directory: /home/mgreco/github/mmngreco/IneqPy/site
ERROR    -  Error reading page 'index.md': 'NoneType' object has no attribute 'strip'
Traceback (most recent call last):
  File "/home/mgreco/.local/share/virtualenvs/IneqPy-eI7PkriJ/bin/mkdocs", line 8, in <module>
    sys.exit(cli())
  File "/home/mgreco/.local/share/virtualenvs/IneqPy-eI7PkriJ/lib/python3.8/site-packages/click/core.py", line 1128, in __call__
    return self.main(*args, **kwargs)
  File "/home/mgreco/.local/share/virtualenvs/IneqPy-eI7PkriJ/lib/python3.8/site-packages/click/core.py", line 1053, in main
    rv = self.invoke(ctx)
  File "/home/mgreco/.local/share/virtualenvs/IneqPy-eI7PkriJ/lib/python3.8/site-packages/click/core.py", line 1659, in invoke
    return _process_result(sub_ctx.command.invoke(sub_ctx))
  File "/home/mgreco/.local/share/virtualenvs/IneqPy-eI7PkriJ/lib/python3.8/site-packages/click/core.py", line 1395, in invoke
    return ctx.invoke(self.callback, **ctx.params)
  File "/home/mgreco/.local/share/virtualenvs/IneqPy-eI7PkriJ/lib/python3.8/site-packages/click/core.py", line 754, in invoke
    return __callback(*args, **kwargs)
  File "/home/mgreco/.local/share/virtualenvs/IneqPy-eI7PkriJ/lib/python3.8/site-packages/mkdocs/__main__.py", line 187, in build_command
    build.build(config.load_config(**kwargs), dirty=not clean)
  File "/home/mgreco/.local/share/virtualenvs/IneqPy-eI7PkriJ/lib/python3.8/site-packages/mkdocs/commands/build.py", line 292, in build
    _populate_page(file.page, config, files, dirty)
  File "/home/mgreco/.local/share/virtualenvs/IneqPy-eI7PkriJ/lib/python3.8/site-packages/mkdocs/commands/build.py", line 174, in _populate_page
    page.render(config, files)
  File "/home/mgreco/.local/share/virtualenvs/IneqPy-eI7PkriJ/lib/python3.8/site-packages/mkdocs/structure/pages.py", line 174, in render
    self.content = md.convert(self.markdown)
  File "/home/mgreco/.local/share/virtualenvs/IneqPy-eI7PkriJ/lib/python3.8/site-packages/markdown/core.py", line 264, in convert
    root = self.parser.parseDocument(self.lines).getroot()
  File "/home/mgreco/.local/share/virtualenvs/IneqPy-eI7PkriJ/lib/python3.8/site-packages/markdown/blockparser.py", line 90, in parseDocument
    self.parseChunk(self.root, '\n'.join(lines))
  File "/home/mgreco/.local/share/virtualenvs/IneqPy-eI7PkriJ/lib/python3.8/site-packages/markdown/blockparser.py", line 105, in parseChunk
    self.parseBlocks(parent, text.split('\n\n'))
  File "/home/mgreco/.local/share/virtualenvs/IneqPy-eI7PkriJ/lib/python3.8/site-packages/markdown/blockparser.py", line 123, in parseBlocks
    if processor.run(parent, blocks) is not False:
  File "/home/mgreco/.local/share/virtualenvs/IneqPy-eI7PkriJ/lib/python3.8/site-packages/mkdocstrings/extension.py", line 120, in run
    html, handler, data = self._process_block(identifier, block, heading_level)
  File "/home/mgreco/.local/share/virtualenvs/IneqPy-eI7PkriJ/lib/python3.8/site-packages/mkdocstrings/extension.py", line 199, in _process_block
    rendered = handler.renderer.render(data, rendering)
  File "/home/mgreco/.local/share/virtualenvs/IneqPy-eI7PkriJ/lib/python3.8/site-packages/mkdocstrings/handlers/python.py", line 96, in render
    return template.render(
  File "/home/mgreco/.local/share/virtualenvs/IneqPy-eI7PkriJ/lib/python3.8/site-packages/jinja2/environment.py", line 1291, in render
    self.environment.handle_exception()
  File "/home/mgreco/.local/share/virtualenvs/IneqPy-eI7PkriJ/lib/python3.8/site-packages/jinja2/environment.py", line 925, in handle_exception
    raise rewrite_traceback_stack(source=source)
  File "/home/mgreco/.local/share/virtualenvs/IneqPy-eI7PkriJ/lib/python3.8/site-packages/mkdocstrings/templates/python/material/module.html", line 53, in top-level templ
ate code
    {% include "children.html" with context %}
  File "/home/mgreco/.local/share/virtualenvs/IneqPy-eI7PkriJ/lib/python3.8/site-packages/mkdocstrings/templates/python/material/children.html", line 30, in top-level tem
plate code
    {% include "class.html" with context %}
  File "/home/mgreco/.local/share/virtualenvs/IneqPy-eI7PkriJ/lib/python3.8/site-packages/mkdocstrings/templates/python/material/class.html", line 54, in top-level templa
te code
    {% include "docstring.html" with context %}
  File "/home/mgreco/.local/share/virtualenvs/IneqPy-eI7PkriJ/lib/python3.8/site-packages/mkdocstrings/templates/python/material/docstring.html", line 8, in top-level tem
plate code
    {% include "attributes.html" with context %}
  File "/home/mgreco/.local/share/virtualenvs/IneqPy-eI7PkriJ/lib/python3.8/site-packages/mkdocstrings/templates/python/material/attributes.html", line 16, in top-level t
emplate code
    <td>{{ attribute.description|convert_markdown(heading_level, html_id) }}</td>
  File "/home/mgreco/.local/share/virtualenvs/IneqPy-eI7PkriJ/lib/python3.8/site-packages/mkdocstrings/handlers/base.py", line 158, in do_convert_markdown
    return Markup(self._md.convert(text))
  File "/home/mgreco/.local/share/virtualenvs/IneqPy-eI7PkriJ/lib/python3.8/site-packages/markdown/core.py", line 248, in convert
    if not source.strip():
AttributeError: 'NoneType' object has no attribute 'strip'

To Reproduce

Fortunately, I could isolate the issue or I think I do it:

Create a file with the following content (I called module for debugging reasons) :

Here's how to document a class using numpy-style

# module.py
class Survey:
    """Survey it's a data structure that handles survey data.

    Attributes
    ----------
    df : pandas.DataFrame
        Data source.

    Methods
    -------
    foo(a=None, b=0.5)
        foo method.
    """
    def __init__(self, df) -> None:
        self.df = df

    def foo(self, a=None, b=0.5):
        pass

Here's my mkdocs.yml:

site_name: IneqPy's Documentation
theme: material
plugins:
- mkdocstrings:
    default_handler: python
    handlers:
      python:
        selection:
          docstring_style: numpy
        rendering:
          show_source: true
    watch:
      - src/ineqpy

Here's the index.md

# Welcome to IneqPy's documentation!


# Reference


::: ineqpy.module

Execute mkdocs build and see the error.

Information (please complete the following information):

• OS: Ubuntu 20.04
• mkdocstrings version: 0.17.0

mkdocs                        1.2.3
mkdocs-autorefs               0.3.1
mkdocs-material               8.1.8
mkdocs-material-extensions    1.0.3
mkdocstrings                  0.17.0

Additional context

This only happens using numpy doc style. I've tried google style and the build works but the html has some problems.

[pawamoy]

Looks like #365, can you check your docstring is properly formatted?

[mmngreco]

all looks ok to me, I use pydocstyle to check and it seems to be ok. Apparently if I drop the Method's section it works:

File content:

# module.py
class Survey:
    """Survey it's a data structure that handles survey data.

    Attributes
    ----------
    df : pandas.DataFrame
        Data source.

-    Methods
-    -------
-    foo(a=None, b=0.5)
-        foo method.
    """

Note: The same happens using the numpydoc's example (which should be well formatted).

[pawamoy]

It seems the underlying parser, docstring_parser, does not support Methods sections.
Feel free to open an issue there, then, if support is implemented, a PR in pytkdocs. Note that the next Python handler does not have support for Methods sections either. I chose not to support them because with the current tooling (inventories, cross-refs, permalinks, material sidebars) such sections feel a bit redundant: you can easily replicate them with a simple Markdown list. The other reason is that I want all parsers to share common features, and I think Methods sections only exist in Numpydoc.

[mmngreco]

Ok, Thank you, I will try to open a issue there. To me hardest part was trying to figure out where was the problem. It's pity. I really wanted to make it works. You may want to add this information in your readme in order to warn to future users of this issue.

[pawamoy]

Indeed, this should be documented, sorry you had trouble with this. Do you want to update the docs in a PR 😄 ?

[mmngreco]

Sure, I will try it! ;-)

[amirmolaviabm]

I want to add a comment here. There are other sections that are not supported like Notes, However, having those sections will not raise an exception and they get silently ignored. However Methods raise and exception, I think there is a bug there that does not ignore Methods.