sphinx-apitree

apitree 是一个小型库，可以以最小的摩擦生成可用的文档！

apitree 负责一切，因此您可以只关注代码。

使用方法

在 docs/conf.py 中，替换所有内容为

import apitree

apitree.make_project(
    # e.g. `import visu3d as v3d` -> {'v3d': 'visu3d'}
    project_name={'alias': 'my_module'},
    globals=globals(),
)

然后生成文档

sphinx-build -b html docs/ docs/_build

要在您的 toctree 中添加 api/my_module/index，例如

..toctree:
  :caption: API

  api/my_module/index

功能

• 全部包含：单次函数调用包括主题、API生成等 ...
• 自动生成API树
  • 不需要 __all__（智能检测哪些符号已记录）
  • 添加可展开的toc树，包含所有符号
• 添加到 GitHub 的链接。
• 默认支持Markdown（.md）/ Jupyter（.ipynb）
• 自动交叉引用（只需在Markdown内联代码中注释 my_symbol，链接会自动添加）
• 与 autodoc 和 apitree 相反，它还记录
  • 类型注解（Union[]，...）
  • 属性
• ...

在项目中安装

1. 在 pyproject.toml 中

   [project.optional-dependencies]
   # Installed through `pip install .[docs]`
   docs = [
       # Install `apitree` with all extensions (sphinx, theme,...)
       "sphinx-apitree[ext]",
   ]
   

2. 在 .readthedocs.yaml 中

   sphinx:
   configuration: docs/conf.py
   
   python:
   install:
       - method: pip
       path: .
       extra_requirements:
           - docs
   

选项

默认情况下，apitree 尝试自动推断一切。但是有时用户想覆盖默认选项。

• 包与模块：默认情况下，所有 __init__.py 定义公共API（记录导入），而模块（module.py）定义实现（不记录导入）。您可以通过在模块定义中添加来显式标记模块为包，以便记录其导入，如下所示

  __apitree__ = dict(
      is_package=True,
  )
  

使用apitree的项目示例

• https://github.com/google-research/visu3d (https://visu3d.readthedocs.io/)
• https://github.com/google-research/dataclass_array (https://dataclass-array.readthedocs.io/)
• https://github.com/google-research/etils (https://etils.readthedocs.io/)
• https://github.com/google-research/kauldron (https://kauldron.readthedocs.io/)

生成于

echo start \
&& cd ../visu3d          && sphinx-build -b html docs/ docs/_build \
&& cd ../dataclass_array && sphinx-build -b html docs/ docs/_build \
&& cd ../etils           && sphinx-build -b html docs/ docs/_build \
&& cd ../kauldron        && sphinx-build -b html docs/ docs/_build \
&& echo finished