asdf8601 · GitHub

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.

Read the original on github.com ↗