Docleaf

您的技术文档，美观地集成

Docleaf可以平滑地集成您的技术和长文档。它是一个Sphinx扩展，可以读取Doxygen XML输出，并无缝地将信息格式化与您的用户文档结合。

• 许可证
• 特性
• 安装
• 使用
• 性能
• 历史

许可证

Docleaf根据Parity公共许可证许可。Parity许可证允许自由使用Docleaf以帮助记录开源项目。如果您有一个希望使用Docleaf记录的封闭源代码项目，则必须购买商业许可证。请参阅Docleaf定价页面以获取更多信息。

如果您有任何问题，请通过电子邮件联系：support@docleaf.io

特性

• 自定义指令，允许您针对C和C++代码库的各个部分。
• 与Sphinx C和C++域集成，以支持轻松链接到生成的输出。
• 基于哈希的内容检查以及时间戳检查，以最大限度地减少Doxygen运行后的增量构建时间。
• 与sphinx.ext.linkcode扩展集成，以支持链接到GitHub仓库中的源代码位置。

安装

可以从PyPI安装Docleaf

pip install docleaf

使用

将docleaf.doxygen作为扩展添加到您的Sphinx conf.py文件中

extensions = ["docleaf.doxygen"]

配置扩展以了解您的源代码存储位置以及为项目生成的Doxygen XML输出。可选地设置默认项目

docleaf_projects = {
  "my_project": {
    "root": "../src",
    "xml": "../doxygen/xml"
  }

}
docleaf_default_project = "my_project"

在您的reStructuredText文件中使用提供的指令

.. doxygenstruct:: ExampleStruct

下面是可用的指令。

指令

为C++类生成文档。

.. doxygenclass:: ClassName

为C或C++结构体生成文档。

.. doxygenstruct:: StructName

为C或C++函数生成文档。

.. doxygenfunction:: function_name

为C或C++枚举生成文档。

.. doxygenenum:: EnumName

为在您的Doxygen设置和代码注释中指定的特定组生成文档。

.. doxygengroup:: group_name

所有指令都接受一个:project:选项来指定要使用的项目，如果您不想使用默认项目。

设置

• docleaf_projects

  一个Python字典，将每个项目名称映射到存储其源代码和Doxygen XML输出的文件夹。

• docleaf_default_project

  当指令本身未指定时，默认要使用的项目。

• docleaf_domain_by_extension

  一个Python字典，将文件扩展名映射到Sphinx域。Docleaf尽可能使用Doxygen的语言分类，但为了更好地控制源文件的分类，使用此设置是有用的。例如

  docleaf_domain_by_extension = {"hpp": "cpp", "h": "c"}
  

  确保所有以.hpp结尾的文件都将被视为C++文件，并使用C++ Sphinx域进行处理，而以.h结尾的文件将被视为C文件，并使用C Sphinx域进行处理。

• docleaf_doxygen_skip

  一个指令列表，描述在生成输出文档时要跳过的Doxygen XML的任何部分。支持的条目包括

  • members:all_caps - 跳过任何名称全部为大写字母和下划线的函数或变量成员（如Doxygen中定义的'memberdef'）。这是为了让用户在需要时过滤掉未处理的C/C++宏。
  • xml-nodes:<node name> - 跳过读取和处理Doxygen XML输出中的给定XML节点及其子节点。支持限于htmlonly节点。

与sphinx.ext.linkcode集成

Docleaf可以与sphinx.ext.linkcode扩展集成，以便在文档中添加[source]链接。支持基于GitHub的仓库链接。

为了使用它，请将sphinx.ext.linkcode扩展添加到Sphinx的conf.py中的extensions列表，并使用带有适当的存储库参数的docleaf.doxygen.GitHubLinkResolver。

extensions = [
  "docleaf.doxygen",
  "sphinx.ext.linkcode",
  ]

linkcode_resolve = docleaf.doxygen.GitHubLinkResolver(
    root="../../../", user="docleaf-labs", repo="docleaf", branch="main"
)

其中

• root是您存储库根的相对路径。
• user是您的GitHub存储库的用户或组织名称。
• repo是您的GitHub存储库的名称。
• tag是您希望生成的链接URL针对的git标签。
• branch是您希望生成的链接URL针对的git分支。
• commit是您希望生成的链接URL针对的git提交SHA。

只需要tag、branch和commit中的一个。

性能

在进行Zephyr RTOS文档套件的干净构建时，Docleaf比Breathe快2.1倍。

Benchmark: docleaf
  Time (mean ± σ):     180.383 s ±  3.213 s    [User: 448.242 s, System: 12.908 s]
  Range (min … max):   175.695 s … 185.187 s    10 runs

Benchmark: breathe
  Time (mean ± σ):     389.658 s ±  5.271 s    [User: 1839.366 s, System: 24.895 s]
  Range (min … max):   379.093 s … 394.315 s    10 runs

历史

Docleaf是由Breathe项目的创建者编写和维护的。它通过将代码库重写为使用Rust来解决Breathe的一些性能和内存消耗问题。用户体验旨在与Breathe相匹配并改进。