maciejmatczak · GitHub

Describe the bug
I think it relates more to mkdocstrings setup and path handling then pytkdocs, but please let me know if issue should be created there.

mkdocs can be used with --config-file switch to provide direct path to a config. Settings in mkdocs.yml like docs_dir are relative to the config path, not current working directory.

It seems different for mkdocstrings when one use PATH based module finding:

plugins:
  - mkdocstrings:
      handlers:
        python:
          setup_commands:
            - "import sys"
            - "sys.path.append('../')"
          rendering:
            show_category_heading: true
            show_root_toc_entry: false

That piece of code is not run relative to a config placement. Build succeeds when run inside repository, fails when run in any different area, it seems.

Expected behavior
Either an explicit way in config to add paths to PYTHONPATH relative to config itself, like:

plugins:
  - mkdocstrings:
      handlers:
        python:
          python_paths:
            - ..
          rendering:
            show_category_heading: true
            show_root_toc_entry: false

Or guarantee that dynamic setup_commands are run in directory where config is placed. I am afraid it might break some behavior if someone expects that.

Screenshots

ERROR    -  mkdocstrings.extension: Importing '<some module>' failed, possible causes are:
            - an exception happened while importing
            - an element in the path does not exist

Information (please complete the following information):

  • mkdocstrings version: 0.15.2

Read the original on github.com ↗