Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly

Appearance settings

Can I prefer my own code when there are duplicated module names? #248

Closed Answered by pawamoy
jwarwick-delfi asked this question in Q&A
Discussion options

First, I'm a big fan of this plugin, thank you to the author and contributors.

Here's my question: when searching for a module, if there are multiple modules on the path with the same name, can I configure the plugin to prefer my source code over modules installed in site-packages?

I've got a project set up as follows:

my_module/
    __init__.py
    ...
    docs/
        tests.md
tests/
    __init__.py
    ...
mkdocs.yml
pyproject.toml

I'm trying to collect documentation from my tests root. tests.md looks like this:

# Testing
::: tests

I believe mkdocs.yml is correctly configured:

plugins:
 - mkdocstrings:
      handlers:
          python:
            paths: [.]

When I render these docs, other python source is correctly collected/rendered, but "tests" is not.
From the logs, it seems like "tests" is actually being loaded from site-packges:

  mkdocstrings: Matched '::: tests'
│    ▹ DEBUG   -  griffe: Searching path(s) for tests
│    ▹ DEBUG   -  griffe: Found tests: loading
│    ▹ DEBUG   -  griffe: Loading path (omitted)/.venv/lib/python3.12/site-packages/tests/__init__.py

From manually looking at this path, it seems like this originates from one of my 3rd party dependencies, a bibtex parser package. I'm hoping there is an easy way to configure the plugin to prioritize my modules.

(edit) I've also tried setting "paths" to paths: [my_module, tests], and got the same result.

Thanks in advance for any help!

You must be logged in to vote

Thanks! Found the issue. We build the list of search paths by concatenating the user provided paths to sys.path. But when inserting in the final list, we check if the path is not already present, and in this case, it's already present, but in last position. In the end site-packages had precedence over the current folder. Will push a fix to mkdocstrings-python right now 🙂

Replies: 2 comments · 4 replies

Comment options

Hi @jwarwick-delfi thank you for the kind words! ❤️

From looking at your config it should pick up the tests module in the current folder 🤔 paths: [.] is the correct (and default) thing to do (paths: [my_module, tests] would not be correct, paths must be search paths, not paths to packages, and I know it's not super clear so I'll probably rename it search_paths in the future 😅).

Do you have a public repository I can try things on?

You must be logged in to vote
3 replies
@jwarwick-delfi
Comment options

Thanks for the confirmation, here's an example repo - please let me know if you're able to reproduce the behavior

https://github.com/jwarwick-delfi/mkdspy-example-tests-issue

@pawamoy
Comment options

Thanks! Found the issue. We build the list of search paths by concatenating the user provided paths to sys.path. But when inserting in the final list, we check if the path is not already present, and in this case, it's already present, but in last position. In the end site-packages had precedence over the current folder. Will push a fix to mkdocstrings-python right now 🙂

Answer selected by pawamoy
@pawamoy
Comment options

Fixed in v1.16.1 🙂

Comment options

Confirmed, your update works for me - thank you so much, especially for the quick response and turnaround!

You must be logged in to vote
1 reply
@pawamoy
Comment options

Thanks for confirming 🎉!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Category
🙏
Q&A
Labels
None yet
2 participants
Morty Proxy This is a proxified and sanitized view of the page, visit original site.