Decorator to ignore specific functions during the docstrings "discovery"

[Skrattoune]

Is your feature request related to a problem? Please describe. My prod is currently in Django 3.2, but I have some unused modules already containing code that will be ready for future versions.

When mkdocstrings is discovering the submodules of my apps, it blocks because there is an unexpected keyword argument: ERROR - mkdocstrings: display() got an unexpected keyword argument 'link'

Describe the solution you'd like I haven't been able to find on the web or in official documentation any means to prevent the autodiscovery of specific functions to prevent this type of error / blockage

Similarly, even when implementing a decorator that prevent the execution of wrapped functions, the error also happened

Similarly, even when implementing a decorator that prevent the execution of wrapped functions, the error also happened

I therefore guess a deeper kowledge of mkdocsstrins is needed to put in place a dedicated decorator to bypass autodiscovery of specific functions

or to put in place other effective alternative to to bypass autodiscovery of specific functions

In any case, it would be great to embed into the official pluggin documentation.

Thanks in advance, Skratt

Additional context Working in Django, I have to use python-legacy, and I here is my mkdocs.yml file:

site_name: MyApp
site_url: https://app.my-app.com/

theme:
  name: "material"
  # theme: readthedocs

plugins:
  - search  # 
  - mkdocstrings:
      handlers:
        python:
          setup_commands:
            - import os
            - import django
            - os.environ.setdefault("DJANGO_SETTINGS_MODULE", "my_app.settings")
            - django.setup()
nav:
  - Overview: index.md
  - Users app: users.md

[pawamoy]

Hello, thanks for the report.

Working in Django, I have to use python-legacy

Why? Because it has better support for Django? Could you explain what you would expect from mkdocstrings in terms of Django support? I'd like to better support it in the new handler, with an extension, like we do for Pydantic.

ERROR - mkdocstrings: display() got an unexpected keyword argument 'link'

Can you run MkDocs in verbose mode and paste the logs? mkdocs build -v

What version of dependencies do you have? pip freeze | grep docs

[Skrattoune]

Working in Django, I have to use python-legacy

Why? Because it has better support for Django?

Hi, it is just stated in the documentation that the new handler does not currently support Django ...

so I didn't even try with the new python handler

---

Update: when I try exactly the same with the new python handler ... verbose mode shows me that I go through all files ... but no reference to code shows on the generated pages

---

What version of dependencies do you have?

dependancies:

Details

amqp==2.5.2 asgiref==3.3.4 astroid==2.4.2 astunparse==1.6.3 bidict==0.21.4 billiard==3.6.3.0 blinker==1.4 bx-django-utils==1 bx-py-utils==37 cached-property==1.5.2 celery==4.4.2 celery-progress==0.0.10 certifi==2023.5.7 charset-normalizer==3.2.0 click==8.1.6 colorama==0.4.3 coverage==5.0.3 Django==3.2 django-admin-sortable==2.1.18 django-admin-sortable2==1.0 django-debug-toolbar==3.2.1 django-extensions==3.1.3 django-filter==2.4.0 django-huey-monitor==0.5.0 django-log-viewer==1.1.4 django-modeladmin-reorder==0.3.1 django-nested-inline==0.4.2 django-rosetta==0.9.9 django-sql-utils==0.5.0 django-user-language-middleware==0.0.3 fuzzywuzzy==0.18.0 ghp-import==2.1.0 griffe==0.30.1 huey==2.4.3 idna==3.4 importlib-metadata==6.7.0 isort==4.3.21 Jinja2==3.1.2 kombu==4.6.8 lazy-object-proxy==1.4.3 Markdown==3.3.7 MarkupSafe==2.1.3 mccabe==0.6.1 mergedeep==1.3.4 mkdocs==1.4.3 mkdocs-autorefs==0.4.1 mkdocs-material==9.1.19 mkdocs-material-extensions==1.1.1 mkdocstrings==0.22.0 mkdocstrings-python==1.1.2 mkdocstrings-python-legacy==0.2.3 model-bakery==1.4.0 nplusone==1.0.0 numpy==1.20.2 packaging==23.1 pandas==1.3.5 Pillow==8.2.0 pip-check==2.7 plotly==5.13.1 polib==1.2.0 Pygments==2.15.1 pylint==2.5.3 pylint-django==2.0.15 pylint-plugin-utils==0.6 pymdown-extensions==10.1 python-dateutil==2.8.2 python-stdnum==1.16 pytkdocs==0.16.1 pytz==2019.3 PyYAML==6.0.1 pyyaml_env_tag==0.1 redis==3.5.3 regex==2023.6.3 requests==2.31.0 scipy==1.6.3 six==1.13.0 sqlparse==0.3.0 tenacity==8.2.2 terminaltables==3.1.10 toml==0.10.1 typed-ast==1.4.1 typing_extensions==4.7.1 urllib3==2.0.4 vine==1.3.0 watchdog==3.0.0 wrapt==1.12.1 zipp==3.1.0

Could you explain what you would expect from mkdocstrings in terms of Django support? I'd like to better support it in the new handler, with an extension, like we do for Pydantic.

That would be great indeed. I'm really not sure why nothing is showing-up when I run mkdocstrings on my python projects from the mkdocs.yml file from before.

I guess that solving this first could be a first step.

How can I support?

[pawamoy]

I see, thanks for your answer.

Indeed the new handler won't pick up description from model fields for example, so rendered docs will look empty. Support for Django is planned in the new handler too, I'll try to get to it soon :slightly_smiling_face: Support will be brought as an extension to Griffe, and this extension will be available to sponsors only.

Other than that, PRs to pytkdocs (used by the legacy handler) are welcome if you'd like to try and fix this issue :slightly_smiling_face: I'll move it to the pytkdocs repo.

[pawamoy]

By the way, I'm not sure to understand the actual issue yet. There's no display function in pytkdocs or mkdocstrings-python-legacy. Does this function come from your own code?