How to add path for a module

[sidhomj]

I think this is a fairly simple question but I haven't been able to solve it. If I have my python package in a different directory than my docs folder, how do I tell mkdocstrings to look at where the python package is?

I'm currently using the below in my .yaml file

plugins:
    - mkdocstrings:
        handlers:
            python:
                setup_commands:
                    - import sys
                    - sys.path.append('../')

[sidhomj]

no matter what I try, I keep getting this error.

ImportError: Importing '' failed, possible causes are:
- an exception happened while importing
- an element in the path does not exist

or this error::

AttributeError: module 'package' has no attribute 'package'

[pawamoy]

Hello @sidhomj

Importing ''

Could you show us your Markdown file? Particularly the autodoc instruction, starting with :::?
Could you also show your project layout? The output of the tree -L 2 command for example.

[sidhomj]

so my file structure looks like this:

-DeepTCR/DeepTCR.py
-docs/mkdocs.yml

and my markdown file has the following:

::: DeepTCR.DeepTCR.DeepTCR_base.Get_Data

and i get this error:

AttributeError: module 'DeepTCR' has no attribute 'DeepTCR'

with this yaml file:

site_name: DeepTCR
nav:
    - Home: index.md
    - Release History: releasehx.md
theme: readthedocs
plugins:
    - mkdocstrings:
        handlers:
            python:
                setup_commands:
                    - import sys
                    - sys.path.append('../')

[pawamoy]

Can you try this:

plugins:
    - mkdocstrings:
        handlers:
            python:
                setup_commands:
                    - import sys
                    - sys.path.append('../')
                selection:
                    new_path_syntax: true

This will help debugging.

[sidhomj]

now i get this error:

    import tensorflow as tf
ModuleNotFoundError: No module named 'tensorflow'

Is this because I have to install all dependencies on the venv storing mkdocs?

[oprypin]

Is this because I have to install all dependencies on the venv storing mkdocs?

Yes, or add it to path as well. If you can run python -c 'import tensorflow' then this will also be able to import it.

[sidhomj]

your solution solved my problem! can you explain the reasoning behind using the new_path_syntax?

[oprypin]

new_path_syntax has no relation to the issue

[pawamoy]

new_path_syntax just helps debugging, because it's more strict about its input path. It's easier to say if a module could not be imported because a dependency is missing. And indeed it helped us here: tensorflow was not installed. See https://mkdocstrings.github.io/pytkdocs/#details-on-new_path_syntax

So to answer, yes, your project and its dependencies must be installed for mkdocstrings to work.
mkdocstrings works through introspection (it actually imports things), so everything needs to be installed 🙂

Closing, but feel free to continue the discussion!

[alexhallam]

I am also having this problem. I can't seem to crack it.

Here is my gha log

Here is my workflow

And my mkdoc

I did attempt

plugins:
    - mkdocstrings:
        handlers:
            python:
                setup_commands:
                    - import sys
                    - sys.path.append('../')                    
                    - python -c 'tablespoon'                    
                    - python -c 'cmdstanpy'
                selection:
                    new_path_syntax: true

but I had no luck

[pawamoy]

When using the legacy (default) Python handler, you must install your project's dependencies as well:

ModuleNotFoundError: No module named 'cmdstanpy'

cmdstanpy is not installed.

[alexhallam]

mkdocs
workflows
GHA error
raw api

Okay. I updated this to install cmdstanpy. It looks like I am having a JSON parse issue now. It is odd because I was able to render the website before adding the additional things in setup_commands. What would you suggest in this case?

plugins:
  - mkdocstrings:
      handlers:
        python:
          setup_commands:
            - import sys
            - sys.path.append('../')
            - pip install cmdstanpy
            - pip install tablespoon
            - python -c 'tablespoon'
            - python -c 'cmdstanpy'
          selection:
            new_path_syntax: true

This is my error below

Run mkdocs gh-deploy --force
INFO     -  Cleaning site directory
INFO     -  Building documentation to directory: /home/runner/work/tablespoon/tablespoon/site
INFO     -  The following pages exist in the docs directory, but are not included in the "nav" configuration:
  - index.md
WARNING  -  A relative path to 'section/skill.md' is included in the 'nav' configuration, which is not found in the documentation files
WARNING  -  Documentation file 'index.md' contains a link to 'docs/FORECAST_METHODS.md' which is not found in the documentation files.
WARNING  -  Documentation file 'index.md' contains a link to 'docs/EXAMPLES.md' which is not found in the documentation files.
WARNING  -  Documentation file 'index.md' contains a link to 'docs/FORECAST_METHODS.md' which is not found in the documentation files.
/opt/hostedtoolcache/Python/3.10.2/x64/lib/python3.10/site-packages/mkdocstrings/handlers/python/__init__.py:13: UserWarning: The 'python-legacy' extra of mkdocstrings will become mandatory in the next release. We have no way to detect if you already specify it, so if you do, please ignore this warning. You can globally disable it with the PYTHONWARNINGS environment variable: PYTHONWARNINGS=ignore::UserWarning:mkdocstrings.handlers.python
  warnings.warn(
  File "<string>", line 1
    import sys; from io import StringIO; from pytkdocs.cli import main as pytkdocs; sys.stdout = StringIO(); import sys; sys.path.append('../'); pip install cmdstanpy; pip install tablespoon; python -c 'tablespoon'; python -c 'cmdstanpy'; sys.stdout.flush(); sys.stdout = sys.__stdout__; pytkdocs(['--line-by-line'])
                                                                                                                                                     ^^^^^^^
SyntaxError: invalid syntax
ERROR    -  mkdocstrings: Error while loading JSON:

Traceback (most recent call last):
  File "/opt/hostedtoolcache/Python/3.10.2/x64/lib/python3.10/site-packages/mkdocstrings/handlers/python/collector.py", line 150, in collect

Aborted with a BuildError!
    result = json.loads(stdout)
  File "/opt/hostedtoolcache/Python/3.10.2/x64/lib/python3.10/json/__init__.py", line 346, in loads
    return _default_decoder.decode(s)
  File "/opt/hostedtoolcache/Python/3.10.2/x64/lib/python3.10/json/decoder.py", line 33[7](https://github.com/alexhallam/tablespoon/runs/5353572245?check_suite_focus=true#step:7:7), in decode
    obj, end = self.raw_decode(s, idx=_w(s, 0).end())
  File "/opt/hostedtoolcache/Python/3.[10](https://github.com/alexhallam/tablespoon/runs/5353572245?check_suite_focus=true#step:7:10).2/x64/lib/python3.10/json/decoder.py", line [35](https://github.com/alexhallam/tablespoon/runs/5353572245?check_suite_focus=true#step:7:35)5, in raw_decode
    raise JSONDecodeError("Expecting value", s, err.value) from None
json.decoder.JSONDecodeError: Expecting value: line 1 column 1 (char 0)

ERROR    -  Error reading page 'section/api.md':
ERROR    -  Could not collect 'tablespoon.forecasters.Naive'
Error: Process completed with exit code 1.

[pawamoy]

You are mixing Python statements with shell commands in setup_commands, it triggers SyntaxError. You must install your dependencie the same way you instal mkdocstrings (in your workflow steps for example).

[alexhallam]

Thanks you! I think that did it.