Mkdocs无法找到modelling.constraints模块问题求助

使用的依赖 #

mkdocs = "^1.4.2"
mkdocstrings = "0.19.0"
mkdocs-material = "8.5.8"
mkdocstrings-python = "0.7.1"

mkdocs.yml配置 #

site_name: Optimization Services Documentation
site_url: "https://example.com"

theme:
  name: "material"
nav:
  - 'index.md'
  - 'reference.md'
plugins:
  - search
  - mkdocstrings:
      handlers:
        python:
          setup_commands:
            - import sys
            - sys.path.append('../')
          selection:
            new_path_syntax: true

reference.md内容 #

# Reference
::: modelling.constraints

目标模块代码（modelling/constraints.py） #

def init_constraints(groupes_chantiers: list[GroupeChantiers],
                     digraph_precedence: nx.DiGraph,
                     graph_coactivite: nx.Graph,
                     model: cp_model.CpModel,
                     **kwargs) -> None:
    """
    Adds constraints to cp_model
    Args:
        groupes_chantiers: 
        digraph_precedence: 
        graph_coactivite: 
        model: 

    Returns: None

    """
    pass

执行mkdocs serve时的错误 #

INFO     -  Building documentation...
INFO     -  Cleaning site directory
INFO     -  DeprecationWarning: 'selection' and 'rendering' are deprecated and merged into a single 'options' YAML key
              File "C:\Users\9821390Z.COMMUN\AppData\Local\pypoetry\Cache\virtualenvs\optimisation-KWHapjG2-py3.9\lib\site-packages\mkdocstrings\extension.py", line 121, in run
                html, handler, data = self._process_block(identifier, block, heading_level)
              File "C:\Users\9821390Z.COMMUN\AppData\Local\pypoetry\Cache\virtualenvs\optimisation-KWHapjG2-py3.9\lib\site-packages\mkdocstrings\extension.py", line 185, in _process_block
                warn(
INFO     -  DeprecationWarning: Parameter `only_exported` is deprecated, use `implicit` instead.
              File "C:\Users\9821390Z.COMMUN\AppData\Local\pypoetry\Cache\virtualenvs\optimisation-KWHapjG2-py3.9\lib\site-packages\mkdocstrings_handlers\python\handler.py", line 195, in collect
                unresolved, iterations = loader.resolve_aliases(only_exported=True, only_known_modules=True)
              File "C:\Users\9821390Z.COMMUN\AppData\Local\pypoetry\Cache\virtualenvs\optimisation-KWHapjG2-py3.9\lib\site-packages\griffe\loader.py", line 181, in resolve_aliases
                warn(
INFO     -  DeprecationWarning: Parameter `only_known_modules` is deprecated, use `external` instead.
              File "C:\Users\9821390Z.COMMUN\AppData\Local\pypoetry\Cache\virtualenvs\optimisation-KWHapjG2-py3.9\lib\site-packages\mkdocstrings_handlers\python\handler.py", line 195, in collect
                unresolved, iterations = loader.resolve_aliases(only_exported=True, only_known_modules=True)
              File "C:\Users\9821390Z.COMMUN\AppData\Local\pypoetry\Cache\virtualenvs\optimisation-KWHapjG2-py3.9\lib\site-packages\griffe\loader.py", line 189, in resolve_aliases
                warn(
ERROR    -  mkdocstrings: modelling.constraints could not be found
ERROR    -  Error reading page 'reference.md':
ERROR    -  Could not collect 'modelling.constraints'

注意：将reference.md改为::: modelling可正常运行，但仅返回__cached__, __file__, __package__等私有属性，确认modelling是Python包，但无法获取其内部内容。

解决方案 #

1. 修正模块路径配置 #

sys.path.append('../')的路径可能不符合你的项目结构。假设你的项目结构是：

project-root/
├── modelling/
│   ├── __init__.py
│   └── constraints.py
└── docs/
    ├── mkdocs.yml
    ├── index.md
    └── reference.md

那么在docs目录下执行mkdocs serve时，../会指向project-root，这部分是对的，但建议改用绝对路径避免歧义，或者直接将包安装到虚拟环境（执行poetry install），无需手动添加sys.path：

setup_commands:
  - import sys, os
  - sys.path.append(os.path.abspath('../'))

2. 更新mkdocstrings配置消除废弃警告 #

原配置中的selection已被废弃，需要合并到options中，同时替换废弃参数：

plugins:
  - search
  - mkdocstrings:
      handlers:
        python:
          setup_commands:
            - import sys, os
            - sys.path.append(os.path.abspath('../'))
          options:
            new_path_syntax: true
            implicit: true  # 替代原only_exported参数
            external: false  # 替代原only_known_modules参数

3. 确保modelling包正确导出内部模块 #

在modelling/__init__.py中添加导出声明，让mkdocstrings能识别内部模块：

# modelling/__init__.py
from . import constraints

__all__ = ["constraints"]

或者直接导出需要的函数：

from .constraints import init_constraints

__all__ = ["init_constraints"]

4. 调整reference.md的引用方式 #

如果已经在__init__.py中导出了模块，原引用::: modelling.constraints即可生效；如果需要直接引用函数，可改为：

# Reference
::: modelling.constraints.init_constraints

内容的提问来源于stack exchange，提问作者Grégory Archambeaud