最终用户将如何访问 Sphinx 为 Python 包生成的文档？

Posted 2023-03-15

【中文标题】最终用户将如何访问 Sphinx 为 Python 包生成的文档？

【英文标题】：How would the end-user access the Sphinx generated documentation for a Python package?

【发布时间】：2017-08-25 11:36:42

【问题描述】：

我在 python 中开发了一个包，并使用 Sphinx 为它创建了文档。

文件夹结构的相关部分如下所示：

my_package
  setup.py
  my_package
    my_module.py
  docs
    index.rst
    _build
      html
        index.html

该软件包将托管在 LAN 中由 PYTHONPATH 引用的某个位置。我的最终用户将使用import my_package 访问我的包。他们不知道文档（或与此相关的包）的位置。使用help(my_package) 只会向用户显示模块内的文档。

那么，我想知道如何让我的最终用户访问 index.html 文件？我想过用一种从指定位置打开 html 文件的方法进行编码，但我不喜欢在路径中硬编码的想法。有这样做的标准方法吗？

【问题讨论】：

为什么不将 Sphinx-Documentation 的路径添加到模块的文档字符串中？

@ChristianSauer 我想到了这一点，但由于文档是包的一部分，我希望有某种方式允许用户从包的任何位置调用index.html已安装。

老实说，是什么阻止您使用您的包部署文档？我已经为我们的一个内部包做到了这一点 - 确保它不会为公共包这样做，但对于我们的内部包，这是部署文档的最简单选择

@ChristianSauer，我将使用我的包部署文档，但我只是想避免告诉用户：转到安装包的任何位置，然后查看 docs > _build > html 并打开index.html 文件以访问文档。这似乎不太整洁......

你使用什么样的编辑器？如果是 pycharm，您可以为包添加额外的文档源。如果没有，最简单的方法是在包、方法和类的文档字符串中添加一个 url。这并不少见，numpy 正是这样做的。

【参考方案1】：

扩展@pkqxdd-s 建议：

您可以轻松获取my_package模块内的文档路径

# my_module.py

def get_docs_index_path():
    import os
    my_package_root = os.path.dirname(os.path.dirname(__file__))
    docs_index = os.path.join(my_package_root, 'docs', '_build', 'html', 'index.html')
    return docs_index

现在您可以将路径添加到my_module 或my_package docstring，这样调用help(my_module) 的用户就会得到类似的东西

... 
# original my_module docstring
...

See sphinx docs at <path to your index>

查看this question 了解如何将get_docs_index_path() 的路径添加到文档字符串中。

【参考方案2】：

因此，如果您唯一担心的是您不知道您的模块将安装在哪里，您可以通过调用your_module.__file__（请参阅this post）来解决这个问题。此外，您还可以使用os.path 模块。例如，调用os.path.dirname(your_module.__file__) 可能会返回您的docs 文件夹所在文件夹的路径。然后，您可以相应地修改路径以访问 .html 文件。

【参考方案3】：

通常，文档单独部署到包中。例如，pandas 存储库（包括 .rst 文件中文档的源代码）保存在 Github，但构建的文档可在 its own url 获得。