错误 mkdocstrings 生成错误“没有名为模块”

Question

我正在使用 mkdocstrings 为我的 python 项目构建一个文档网站。

为了生成代码参考文件，我遵循了此说明https://mkdocstrings.github.io/recipes/

我收到这些错误：

    INFO     
    -  Building documentation... INFO     
    -  Cleaning site directory INFO     
    -  The following pages exist in the docs directory, but are not included in the "nav" configuration:               - reference\SUMMARY.md               
    - reference_init_.md 
    ... ...               
    - reference\tests\manual_tests.md ERROR    
    -  mkdocstrings: No module named ' ' ERROR    
    -  Error reading page 'reference/init.md': ERROR    
    -  Could not collect ' '

这是我的文件结构：

这是我的文档文件夹：

我有页面中显示的相同的 gen_ref_pages.py 文件：

    from pathlib import Path

    import mkdocs_gen_files

    nav = mkdocs_gen_files.Nav()

    for path in sorted(Path("src").rglob("*.py")):
        module_path = path.relative_to("src").with_suffix("")
        doc_path = path.relative_to("src").with_suffix(".md")
        full_doc_path = Path("reference", doc_path)

        parts = tuple(module_path.parts)

        if parts[-1] == "__init__":
            parts = parts[:-1]
        elif parts[-1] == "__main__":
            continue

        nav[parts] = doc_path.as_posix()  # 

        with mkdocs_gen_files.open(full_doc_path, "w") as fd:
            ident = ".".join(parts)
            fd.write(f"::: {ident}")

        mkdocs_gen_files.set_edit_path(full_doc_path, path)

    with mkdocs_gen_files.open("reference/SUMMARY.md", "w") as nav_file:  # 
        nav_file.writelines(nav.build_literate_nav())  #    ```

This is my mkdocs.yml:

```    site_name: CA Prediction Docs

    theme:
      name: "material"
      palette:
        primary: deep purple
      logo: assets/logo.png
      favicon: assets/favicon.png
      features:
        - navigation.instant
        - navigation.tabs
        - navigation.expand
        - navigation.top
        # - navigation.sections
        - search.highlight
        - navigation.footer
      icon:
        repo: fontawesome/brands/git-alt

    copyright: Copyright © 2022 - 2023 Ezequiel González

    extra:
      social:
        - icon: fontawesome/brands/github
          link: https://github.com/ezegonmac
        - icon: fontawesome/brands/linkedin
          link: https://www.linkedin.com/in/ezequiel-gonzalez-macho-329583223/

    repo_url: https://github.com/ezegonmac/TFG-CellularAutomata
    repo_name: ezegonmac/TFG-CellularAutomata

    plugins:
      - search
      - gen-files:
          scripts:
          - docs/gen_ref_pages.py
      - mkdocstrings

    nav:
      - Introduction: index.md
      - Getting Started: getting-started.md
      - API Reference: reference.md
      # - Reference: reference/
      - Explanation: explanation.md

Answer 1

在 mkdocstrings 文档之后我也收到了同样的错误。经过一番修改后，我通过添加

paths: [src]

（见下文）成功地提供了文档。

mkdocs.yml

plugins:
  - search
  - gen-files:
      scripts:
        - docs/gen_ref_pages.py
  - mkdocstrings:
      default_handler: python
      handlers:
        python:
          paths: [src]

Answer 2

对于在 2024 年遇到此错误的任何人，只需安装 mkdocstrings-python 即可。

对于点

pip install "mkdocstrings[python]"

为了诗歌

poetry add "mkdocstrings[python]"

现在在您的 Markdown 中，您可以使用以下语法引用实际的 py 文件。

参考来源

# API Reference

---
## Pydantic Models

:::api.monitoring_api.models.pydantic.base
:::api.monitoring_api.models.pydantic.notifications
:::api.monitoring_api.models.pydantic.configurations

---
## Services

:::api.monitoring_api.services.notifications

这里有一个关于 Real Python 的很好的教程