0

我有几个项目，每个项目一个存储库。其中一个存储库管理全局文档，所有其他存储库都是 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 从此主文档构建生成页面。

4

0 回答 0