Sphinx AutoAPI项目指南

Sphinx AutoAPI项目指南

sphinx-autoapiA new approach to API documentation in Sphinx.项目地址:https://gitcode.com/gh_mirrors/sp/sphinx-autoapi

1. 项目目录结构及介绍

Sphinx AutoAPI 是一个为Sphinx扩展而生的工具，旨在无需实际运行或导入被文档化的项目即可自动生成完整的API文档。它通过解析源代码来发现并生成文档，这与传统的Sphinx autodoc 需要手动编写部分文档并且依赖于代码导入的方式有所不同。

主要目录结构：

• docs: 包含项目的文档源码，使用Sphinx语法编写的。
• sphinx_autoapi: 核心源码所在目录，拥有处理文档生成的主要逻辑。
  • src: 实际的Python模块，包含了各种处理类和函数。
  • templates: 自定义模板文件夹，用于定制生成文档的HTML样式。
• tests: 单元测试和集成测试代码，确保扩展的稳定性和功能完整。
• examples: 提供给用户的示例项目，帮助理解如何应用到自己的项目中。
• setup.py: Python项目的安装脚本，用于将Sphinx AutoAPI打包发布。
• .readthedocs.yml: Read the Docs配置文件，用于自动化构建文档网站。
• docs/conf.py: Sphinx配置文件，设置AutoAPI插件和其他Sphinx相关配置。

2. 项目的启动文件介绍

对于Sphinx AutoAPI而言，并没有传统意义上的“启动文件”，因为它的运行是集成在Sphinx构建过程中的。但有两个关键文件对启动文档生成至关重要：

• setup.py: 这个不是直接启动AutoAPI的文件，但它用于安装Sphinx AutoAPI作为其他项目的依赖项，使文档构建环境准备就绪。
• Sphinx的配置文件 (docs/conf.py): 在这个文件中，你需要激活AutoAPI扩展并通过配置选项指定哪些源代码应该被解析来生成文档。这是控制AutoAPI行为的关键点。

3. 项目的配置文件介绍

主要关注点在于Sphinx的配置文件 conf.py 中关于AutoAPI的部分。以下是一些基本配置示例：

extensions = ['autoapi.extension']
autoapi_dirs = ['../your_project/source_code'] # 指定源代码位置
autoapi_root = 'api' # 文档生成的根目录
autoapi_template_dir = '_templates/autoapi' # 可自定义模板路径
autoapi_keep_files = True # 是否保留生成的rst文件
autoapi_options = [
    'members', 
    'special-members', 
    'undoc-members', 
    'show-inheritance',
] # 控制哪些成员被包括进文档

这些配置告诉Sphinx AutoAPI从哪里获取源代码，怎样组织生成的文档，并且哪些元素应该包含在最终的API文档中。确保在使用前阅读其详细的参考指南，以充分利用所有可用的配置选项。

sphinx-autoapiA new approach to API documentation in Sphinx.项目地址:https://gitcode.com/gh_mirrors/sp/sphinx-autoapi