快速入门

sphinx-ape 是一个用于Sphinx框架的文档插件。此插件的目的在于共享代码以生成所有ApeWorX存储库中的文档。

依赖关系

• python3 版本 3.9 到 3.12。

安装

从GitHub安装包

pip install git+https://github.com/ApeWorX/sphinx-ape.git@main

注意： 您也可以首先克隆包并本地安装。

尝试 sphinx-ape --help 检查是否已安装。

快速使用

要使用此Sphinx插件，首先生成文档结构（在项目目录中运行）

sphinx-ape init .

它将生成一个包含一些必要配置文件的 docs/ 文件夹，以及一个指向您的 README.md 的快速入门指南。

现在，您可以从三个目录中放置文档源开始编写Sphinx文档。

1. userguides/ - 包含使用您的包的指南的目录。
2. commands/ - 用于基于命令行引用的 sphinx-click 插件的 .rst 文件。
3. methoddocs/ - 控制您生成的函数文档的Autodoc .rst 文件。

一旦开发完文档，请确保已安装 sphinx-ape 。例如，克隆此存储库并使用 pip install <path/to/sphinx-ape> 或通过 pip install sphinx-ape 从 pypi 安装。

安装 sphinx-ape 后，通过以下步骤构建项目的文档：

sphinx-ape build <path/to/project>

通常情况下，您已经处于项目目录中，因此可以直接执行：

sphinx-ape build .

然后，要查看文档，运行 serve 命令

sphinx-ape serve <path/to/project>
# When in directory already
sphinx-ape serve .

要在提供服务的同时自动打开浏览器，请使用 --open 标志

sphinx-ape serve . --open

要运行文档测试，请使用 sphinx-ape test 命令

sphinx-ape test .

GitHub 动作

此 GitHub 动作旨在构建核心 Ape 以及任何 Ape 插件的文档。此动作也可能适用于具有类似于 Ape 的文档策略的常规 Python 包。

有三个 GitHub 事件可以触发此动作

1. 推送到 'main'：我们构建到 'latest/'。GitHub 动作将提交这些更改到 'gh-pages' 分支。

2. 发布：我们将 'latest/' 复制到发布目录，以及到 'stable/'。GitHub 动作将提交这些更改到 'gh-pages' 分支。

3. 拉取请求或本地开发：我们确保构建成功。

GitHub Pages

为了设置此动作以使用 GitHub Pages，并使发布工作流程正常工作，首先创建一个名为 gh-pages 的分支并将其推送到 GitHub。然后，删除除简单的 README.md、.gitignore 文件和 LICENSE 文件之外的所有内容。一旦全部推送，请转到“页面”选项卡以验证是否为您创建了一个网站。现在，在合并到 main 和发布时，此网站应该会更新（如果您正在使用该动作）。

要本地发布文档，请使用 publish 命令

sphinx-ape publish .

开发

请参阅贡献指南，了解如何为此项目做出贡献。评论、问题、批评和拉取请求都受到欢迎。