Configure pytkdocs

[ritchie46]

Is it possible to configure pytkdocs directly from this libraries config? For instance for using numpy style docstrings.

[aschmu]

Hello Richie I actually contributed the numpy style docstring to pytkdocs but I have no idea how to setup mkdocstrings so that it uses numpy formatted docstrings 😄.

[pawamoy]

Hey @ritchie46, it's documented here 🙂

And I see that we forgot to update this part of the docs to add numpy ^^

[oprypin]

This is documented in the Python handler.

You pass docstring_style under selection options, either per-identifier or globally. The usage documentation shows how to pass options.

[pawamoy]

@aschmu, just curious, do you use pytkdocs directly? Or did you contribute numpy support for other users than yourself?

[aschmu]

I initially wanted to use it at work because we follow the numpy style docstring convention but I thought it would be best to contribute directly to the upstream repo. I haven't yet gotten around to setting up mkdocs, though but I will soon.

[pawamoy]

I see, thanks 🙂

@ritchie46 I'll close this since I think we answered your question!

[ritchie46]

Thanks for the quick response!

[heitorlessa]

Came to look for Numpy support too as the docs say only Google and RST docstrings.

Is that still the case or docs can be updated saying it does support?

I'm gonna give this a try today

[heitorlessa]

Just got it working -- However when it fails it's hard to debug what caused it. I'm also new to the project so pardon if I missed this being documented elsewhere.

Digging a bit I can see mkdocstrings is receiving a None as text and propagates this None to the markdown library which fails as they're not handling None.

mkdocstrings/src/mkdocstrings/handlers/base.py

Line 156 in 87c55fb

return Markup(self._md.convert(text))

https://github.com/Python-Markdown/markdown/blob/6f024f5be53d348b17a5da2c3e9c32c37013efd7/markdown/core.py#L248

        # Fixup the source text
        if not source.strip():
            return ''  # a blank unicode string

While I could make a PR to handle None it wouldn't help understand where it's failing too -- @pawamoy @aschmu, any suggestions on how I could contribute?

Merci!

---

mkdocs.yml

plugins:
  - git-revision-date
  - search
  - mkdocstrings:
      handlers:
        python:
          selection:
            docstring_style: numpy  # then add pytkdocs[numpy-style] dependency

A working example

Stack trace of one class it couldn't finish parsing

WARNING -  mkdocstrings.handlers.python: aws_lambda_powertools.logging.logger.Logger.inject_lambda_context: No type annotation for parameter 'POWERTOOLS_LOGGER_LOG_EVENT' 
ERROR   -  Error reading page 'api.md': 'NoneType' object has no attribute 'strip' 
Traceback (most recent call last):
  File "/Users/lessa/.pyenv/aws-lambda-powertools-FZsWRE5--py3.7/bin/mkdocs", line 8, in <module>
    sys.exit(cli())
  File "/Users/lessa/.pyenv/aws-lambda-powertools-FZsWRE5--py3.7/lib/python3.7/site-packages/click/core.py", line 1137, in __call__
    return self.main(*args, **kwargs)
  File "/Users/lessa/.pyenv/aws-lambda-powertools-FZsWRE5--py3.7/lib/python3.7/site-packages/click/core.py", line 1062, in main
    rv = self.invoke(ctx)
  File "/Users/lessa/.pyenv/aws-lambda-powertools-FZsWRE5--py3.7/lib/python3.7/site-packages/click/core.py", line 1668, in invoke
    return _process_result(sub_ctx.command.invoke(sub_ctx))
  File "/Users/lessa/.pyenv/aws-lambda-powertools-FZsWRE5--py3.7/lib/python3.7/site-packages/click/core.py", line 1404, in invoke
    return ctx.invoke(self.callback, **ctx.params)
  File "/Users/lessa/.pyenv/aws-lambda-powertools-FZsWRE5--py3.7/lib/python3.7/site-packages/click/core.py", line 763, in invoke
    return __callback(*args, **kwargs)
  File "/Users/lessa/.pyenv/aws-lambda-powertools-FZsWRE5--py3.7/lib/python3.7/site-packages/mkdocs/__main__.py", line 136, in serve_command
    **kwargs
  File "/Users/lessa/.pyenv/aws-lambda-powertools-FZsWRE5--py3.7/lib/python3.7/site-packages/mkdocs/commands/serve.py", line 141, in serve
    config = builder()
  File "/Users/lessa/.pyenv/aws-lambda-powertools-FZsWRE5--py3.7/lib/python3.7/site-packages/mkdocs/commands/serve.py", line 136, in builder
    build(config, live_server=live_server, dirty=dirty)
  File "/Users/lessa/.pyenv/aws-lambda-powertools-FZsWRE5--py3.7/lib/python3.7/site-packages/mkdocs/commands/build.py", line 271, in build
    _populate_page(file.page, config, files, dirty)
  File "/Users/lessa/.pyenv/aws-lambda-powertools-FZsWRE5--py3.7/lib/python3.7/site-packages/mkdocs/commands/build.py", line 171, in _populate_page
    page.render(config, files)
  File "/Users/lessa/.pyenv/aws-lambda-powertools-FZsWRE5--py3.7/lib/python3.7/site-packages/mkdocs/structure/pages.py", line 175, in render
    self.content = md.convert(self.markdown)
  File "/Users/lessa/.pyenv/aws-lambda-powertools-FZsWRE5--py3.7/lib/python3.7/site-packages/markdown/core.py", line 263, in convert
    root = self.parser.parseDocument(self.lines).getroot()
  File "/Users/lessa/.pyenv/aws-lambda-powertools-FZsWRE5--py3.7/lib/python3.7/site-packages/markdown/blockparser.py", line 90, in parseDocument
    self.parseChunk(self.root, '\n'.join(lines))
  File "/Users/lessa/.pyenv/aws-lambda-powertools-FZsWRE5--py3.7/lib/python3.7/site-packages/markdown/blockparser.py", line 105, in parseChunk
    self.parseBlocks(parent, text.split('\n\n'))
  File "/Users/lessa/.pyenv/aws-lambda-powertools-FZsWRE5--py3.7/lib/python3.7/site-packages/markdown/blockparser.py", line 123, in parseBlocks
    if processor.run(parent, blocks) is not False:
  File "/Users/lessa/.pyenv/aws-lambda-powertools-FZsWRE5--py3.7/lib/python3.7/site-packages/mkdocstrings/extension.py", line 120, in run
    html, headings = self._process_block(identifier, block, heading_level)
  File "/Users/lessa/.pyenv/aws-lambda-powertools-FZsWRE5--py3.7/lib/python3.7/site-packages/mkdocstrings/extension.py", line 180, in _process_block
    rendered = handler.renderer.render(data, rendering)
  File "/Users/lessa/.pyenv/aws-lambda-powertools-FZsWRE5--py3.7/lib/python3.7/site-packages/mkdocstrings/handlers/python.py", line 77, in render
    **{"config": final_config, data["category"]: data, "heading_level": heading_level, "root": True},
  File "/Users/lessa/.pyenv/aws-lambda-powertools-FZsWRE5--py3.7/lib/python3.7/site-packages/jinja2/environment.py", line 1304, in render
    self.environment.handle_exception()
  File "/Users/lessa/.pyenv/aws-lambda-powertools-FZsWRE5--py3.7/lib/python3.7/site-packages/jinja2/environment.py", line 925, in handle_exception
    raise rewrite_traceback_stack(source=source)
  File "/Users/lessa/.pyenv/aws-lambda-powertools-FZsWRE5--py3.7/lib/python3.7/site-packages/mkdocstrings/templates/python/material/class.html", line 45, in top-level template code
    {% include "docstring.html" with context %}
  File "/Users/lessa/.pyenv/aws-lambda-powertools-FZsWRE5--py3.7/lib/python3.7/site-packages/mkdocstrings/templates/python/material/docstring.html", line 12, in top-level template code
    {% include "parameters.html" with context %}
  File "/Users/lessa/.pyenv/aws-lambda-powertools-FZsWRE5--py3.7/lib/python3.7/site-packages/mkdocstrings/templates/python/material/parameters.html", line 17, in top-level template code
    <td>{{ parameter.description|convert_markdown(heading_level, html_id) }}</td>
  File "/Users/lessa/.pyenv/aws-lambda-powertools-FZsWRE5--py3.7/lib/python3.7/site-packages/mkdocstrings/handlers/base.py", line 155, in do_convert_markdown
    return Markup(self._md.convert(text))
  File "/Users/lessa/.pyenv/aws-lambda-powertools-FZsWRE5--py3.7/lib/python3.7/site-packages/markdown/core.py", line 247, in convert
    if not source.strip():

AttributeError: 'NoneType' object has no attribute 'strip'

[oprypin]

@heitorlessa That seems like a useful report and I'll check it out soon. But looks like an entirely new issue?

[heitorlessa]

@heitorlessa That seems like a useful report and I'll check it out soon. But looks like an entirely new issue?

Absolutely. I posted hoping there was an undocumented way to enable debugging through pytkdocs.

Want me to create a new issue here or in pytkdocs repo?

[oprypin]

@heitorlessa Yes, please open an issue. It definitely spans both repos but seems like more on mkdocstrings side.