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'

如果我将 reference.md 替换为::: modelling但仅返回私有函数，它就可以工作__cached__, __file__, __package__...
这只是让我确定建模是一个 python 包，但我无法获取其中的内容。

此外，我正在将它与另一个mkdocs serve效果良好的项目进行比较，所以我很困惑。

感谢您的帮助。

Answer 1

我在python项目中也遇到了类似的问题。mkdocs serve仅适用于少数项目文件夹中的 python 文件，但不适用于其他一些文件夹 ( ERROR - Could not collect ...) 中的 python 文件。

我将一个 python 文件从不起作用的文件夹复制到起作用的文件夹，然后可以通过运行来成功收集该文件mkdocs serve。

就我而言，我们发现所有可用的文件夹都有一个__init__.py文件将它们标识为常规包文件夹。

我的问题是通过将__init__.py文件添加到我们要从中mkdocs serve收集文件的文件夹并将其设为常规包文件夹来解决的。

希望这对您的情况有所帮助！