编写文档

高质量、一致的天文学代码文档是天文项目的主要目标之一。因此，我们在这里描述我们的文档处理程序和规则。对于astropy核心项目和协调的软件包，我们尽可能地遵守这些标准，我们鼓励附属软件包也遵守这些标准，因为它们鼓励有用的文档，而这是专业天文学软件通常缺乏的特性。

添加Git提交

当您的更改只影响文档（即docstring或RST文件）而不包括任何需要doctest运行的代码段时，您可以添加一个 [ci skip] 在你的提交消息中。例如：：

git commit -m "Update documentation about this and that [ci skip]"

当此提交推送到与拉请求关联的分支时，将跳过所有CI，因为它不是必需的。这是因为文档构建驻留在RTD中，而RTD当前不考虑 [ci skip] 指令。

从源代码构建文档

有关从源代码构建文档的信息，请参见 建筑文件 安装说明中的章节。

Astropy文档规则和指南

本节描述了任何考虑集成到核心包中的贡献都应该遵循的文档标准，以及标准的Astropy docstring格式。

  • 所有文档文本应遵循 Astropy叙事风格指南：供投稿人使用的写作资源 .

  • 所有文件应使用 Sphinx 文档工具。

  • 这个 package template 提供建议的文档总体结构。

  • 必须为所有公共类、方法和函数提供docstring。

  • Docstrings应该跟在 numpydoc format .

  • 对于特定模块或类的典型用例，强烈建议使用示例和/或教程。

  • 任何外部包依赖关系都必须在文档中明确提及。它们也应记录在 setup.cfg 在astropy存储库的根目录中使用 extras_require 条目。

  • 配置选项使用 astropy.config 必须在文档中明确提到机制。

Sphinx文档主题

一个Astropy项目sphinxhtml主题包含在 astropy-sphinx-theme 包裹。这就允许Astropy和附属软件包都可以使用这个主题。通过在中的全局Astropy sphinx配置中设置主题来激活主题 sphinx-astropy, 这是导入 Sphinx 配置的Astropy和附属软件包。

可以通过重写全局配置中设置的几个sphinx配置变量来使用不同的主题。

  • 要使用不同的主题，请设置 html_theme 所需的内置 Shpinx 主题或中的自定义主题的名称 package-name/docs/conf.py （何处） 'package-name' 是“astropy”或附属软件包的名称）。

  • 要使用自定义主题，另外：将主题放置在 package-name/docs/_themes 并添加 '_themes' 到 html_theme_path 变量。见 Sphinx 有关主题的更多详细信息的文档。

Shpinx 扩展

Astropy的文档构建过程使用了许多sphinx扩展，这些扩展在安装时都是自动安装的 sphinx-astropy. 这有助于以同质和可读的方式轻松地记录代码。

使用的主要扩展包括：

此外， sphinx-astropy 包括一些小扩展：

  • sphinx_astropy.ext.edit_on_github -一个扩展，用于向文档页添加“在GitHub上编辑”链接。

  • sphinx_astropy.ext.changelog_links -一个扩展，用于在呈现变更日志时添加用于拉取请求的链接。

  • sphinx_astropy.ext.doctest -一个扩展，可以在里面添加关于doctest的元数据 .rst 文件夹