numpy-style broken on class docstring
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) :
# 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
mkdocstringsversion: 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.