Mkdocs 无法找到模块

Question

我正在尝试使用以下方法生成自动化文档：

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

index.md 仍然是 mkdocs new 生成的默认文件。

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 会返回：

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'

如果我用

::: modelling

替换reference.md，它会起作用，但只返回私有函数

__cached__, __file__, __package__

...
这只是让我确定建模是一个 python 包，但我无法获取其中的内容。

此外，我正在将它与另一个

mkdocs serve

效果很好的项目进行比较，所以我很困惑。

感谢您的帮助。

Answer 1

我在python项目中也遇到了类似的问题。

mkdocs serve

仅适用于少数项目文件夹中的 python 文件，但不适用于其他一些文件夹中的 python 文件 (

ERROR - Could not collect ...

)。

我将一个 python 文件从不起作用的文件夹复制到一个起作用的文件夹，然后可以通过运行

mkdocs serve

成功收集该文件。

就我而言，发现所有可用的文件夹都有一个

__init__.py

文件，将它们标识为常规包文件夹。

通过将

__init__.py

文件添加到我们想要

mkdocs serve

收集文件的文件夹并将其设为常规包文件夹，解决了我的问题。

希望这对您有帮助！