python - Sphinx 包含来自包的文档
问题描述
我有几个项目,每个项目一个存储库。其中一个存储库管理全局文档,所有其他存储库都是 python 包。
我想保持每个包文档独立(不仅是模块文档,还有安装说明/示例/等)。换句话说,每个包都负责自己的文档。
主文档存储库应包含所有文档(并在其上添加一些结构以及一些文本以将所有这些包链接在一起)。我正在寻找比我现在拥有的更简单/更清洁的解决方案。
当前解决方案
包文件
每个包都有一个doc/
文件夹,其中包含两个module_description.rst
(结构化自动文档语句)。例如,package_name
这看起来或多或少像这样:
Interface
----------
.. autoclass:: package_name.AbstractClass
:members:
:undoc-members:
:member-order: bysource
Basic implementations
---------------------
.. autoclass:: package_name.ImplementationOne
:members:
:undoc-members:
:member-order: bysource
.. autoclass:: package_name.ImplementationTwo
:members:
:undoc-members:
:member-order: bysource
我拥有的第二个文件index.rst
看起来像:
.. toctree::
:glob:
:hidden:
:maxdepth: 2
module_description
tutorials/*
examples/*
############
Package Name
############
Install instructions
====================
.. code-block:: bash
pip install package_name
主文档
主文档包括对仅包含一行的文档的引用:
.. include:: ../../submodules/package_name/doc/_sources/index.rst
正如您可能猜到的那样,为了完成这项工作,我使用了一个指向package_name
存储库并允许我获取文件的 git 子模块package_name/doc/_sources/index.rst
。单独这样做是行不通的,因为 autodoc 语句找不到模块package_name
。
因此,我需要在主文档中安装该软件包。我有两个选择,要么从子模块安装它,要么直接从包注册表安装(两者都适合我)。
问题
我可以避免添加 git 子模块而只安装package_name
吗?如果是这样,我如何doc/index.rst
从主要的 sphinx 文档中包含它?
也许还有更好的方法,但我找不到任何关于此的文章。欢迎任何参考,因为我很难找到合适的词来询问我的搜索引擎朋友。
请注意,我有一个约束,我希望 gitlab 从此主文档构建生成页面。
解决方案
推荐阅读
- mysql - 如何使用 node 和 mysql 将值从 DB 返回到变量?
- android - Firebase DB 离线缓存如何在 android 上工作?
- excel - 获取不在列表中的值的数量
- c# - 将自包含的 .Net Core Windows 窗体应用程序发布到单个文件中
- bash - 只读以 bash 中传递给脚本的变量开头的行
- firebase - 使用 firebase 在颤振中设置“结构化查询”时出错
- docker - 将串行 USB 设备暴露给容器
- ios - iOS Firebase / Firestore - 数组计数多少次读取
- ios - UITextView 用新行向上滚动表格视图
- windows - 如何让 AWS GPU 在 Windows Server 上运行?