Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

show_if_no_docstring does not collect objects with no docstring in new Python handler #388

Closed
johnthagen opened this issue Feb 21, 2022 · 3 comments
Labels
unconfirmed This bug was not reproduced yet

Comments

@johnthagen
Copy link
Contributor

johnthagen commented Feb 21, 2022

Describe the bug

Enabling show_if_no_docstring in the new Python handler (#364) setting does not collect packages or modules without a docstring.

  - mkdocstrings:
      handlers:
        python:
          selection:
            show_if_no_docstring: true

To Reproduce

A full reproducible project is here:

Steps to reproduce the behavior:

  1. In that PR, install tox and run tox -e docs-serve
  2. Navigate to the API page:

Screen Shot 2022-02-21 at 3 18 00 PM

Expected behavior
As with the legacy Python handler, there would be a way to collect all files in a package, regardless of if some of the items in the tree have a docstring.

Information (please complete the following information):

  • OS: MacOS
  • Browser: Chrome
  • mkdocstrings version: 0.18.0

Full requirements: https://github.com/johnthagen/python-blueprint/pull/82/files#diff-43470c4f399e798afc682f0bf6c690eef5f47ee25445904a066e4c3314f3a787

Additional Context

Full mkdocs.yml:

# Set strict to true to turn warnings into errors to catch warnings within CI.
strict: true
theme:
  name: material
  # By default, fonts are pulled from Google on the Internet. To support offline usage, this is
  # disabled.
  font: false
  palette:
    scheme: slate
    primary: green
    accent: yellow
  icon:
    logo: material/math-integral-box
    # GitHub specific.
    repo: fontawesome/brands/github
  favicon: static/math-integral-box.png
  features:
    - content.code.annotate
    - navigation.tracking
    - search.highlight
    - search.share
    - search.suggest
markdown_extensions:
  - admonition
  - pymdownx.keys
  - pymdownx.highlight
  - pymdownx.superfences
  - pymdownx.snippets
  - pymdownx.tabbed:
      alternate_style: true
extra:
  social:
    - icon: fontawesome/brands/github
      link: https://github.com/johnthagen/python-blueprint
# This is needed to allow links to work when opened from the file system.
use_directory_urls: false
plugins:
  - search
  - mkdocstrings:
      handlers:
        python:
          selection:
            show_if_no_docstring: true
      watch:
          - src
  # This plugin is used to validate URLs (including some anchors).
  # Uncomment to build the docs with this validation enabled.
  # This is commented out by default because this requires network I/O to validate URLs, so it is
  # inherently not exactly reproducible. But this plugin is none-the-less helpful at detecting
  # incorrect URLs.
#  - htmlproofer:
#      raise_error: True
site_name: fact
copyright: Copyright © 2018-2021 John Hagen
# GitHub Specific Configuration.
repo_name: python-blueprint
repo_url: https://github.com/johnthagen/python-blueprint
edit_uri: edit/master/docs/user_guide/docs/
@johnthagen johnthagen added the unconfirmed This bug was not reproduced yet label Feb 21, 2022
@johnthagen
Copy link
Contributor Author

A version that is built with the legacy handler is currently hosted here: https://johnthagen.github.io/python-blueprint/api.html

@pawamoy
Copy link
Member

pawamoy commented Feb 21, 2022

Try to put show_if_no_docstring under rendering instead of selection 😉

@johnthagen
Copy link
Contributor Author

🤦 I see now that the examples are below the definition. This makes sense now that I know. As a new user reading the docs, the selection example is so close to the top of Rendering I didn't realize that Rendering had it's own examples further down.

Not sure there is anything actionable, but at least you got some feedback from a first time user.

Thanks for the great package!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
unconfirmed This bug was not reproduced yet
Projects
None yet
Development

No branches or pull requests

2 participants