Skip to content

Can't build documentation with PYTHONPATH based module discovery from different directory than repository itself #311

@maciejmatczak

Description

@maciejmatczak

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

Metadata

Metadata

Assignees

No one assigned

    Labels

    bugSomething isn't workingconfigRelated to configuration optionstop-priorityAbsolute priority

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions