最终用户如何访问由Sphinx生成的Python软件包文档？

Question

我已经用Python开发了一个包，并使用Sphinx为其创建了文档。

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

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

该软件包将被托管在局域网中某个由PYTHONPATH引用的位置。最终用户只需使用"import my_package"即可访问我的软件包。他们不会知道文档（或软件包）位于何处。使用"help(my_package)"仅会向用户显示模块内部的文档。

因此，我想知道如何允许我的最终用户访问index.html文件？我考虑编写一个方法来从指定位置打开html文件，但是我不喜欢硬编码路径的想法。有没有标准的方法来解决这个问题？

- bluprince13

---

为什么不将Sphinx文档路径添加到模块的docstring中呢？ - Christian Sauer

@ChristianSauer 我也考虑过这个问题，但是由于文档是包的一部分，我希望用户可以从安装包的任何位置调用“index.html”的某种方式。 - bluprince13

说实话，你到底有什么阻止你将文档与包一起部署的呢？ 对于我们内部的一个软件包，我已经这样做了——当然，对于一个公共的软件包来说，这样做可能行不通，但对于我们内部的软件包来说，这是最简单的选项，可以使文档得到发布。 - Christian Sauer

@ChristianSauer，我将会在我的软件包中部署文档，但是我不想让用户去找安装包的位置，然后再打开docs > _build > html文件夹并且打开index.html文件来查看文档。这样做似乎不太方便... - bluprince13

你使用什么编辑器？如果是PyCharm，你可以为包添加额外的文档源。如果不是，最简单的方法是将包、方法和类的docstrings添加一个URL。这并不罕见，numpy就是这样做的。 - Christian Sauer

Answer 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文档字符串中，这样调用help(my_module)的用户将获得类似以下内容的信息。

... 
# original my_module docstring
...

See sphinx docs at <path to your index>

请查看此问题以了解如何将get_docs_index_path()的路径添加到文档字符串中。

- matusko

Answer 2

所以，如果你唯一的担忧是不知道你的模块将被安装在哪里，你可以通过调用your_module.__file__（参见this post）来找出。此外，你还可以利用os.path模块。例如，调用os.path.dirname(your_module.__file__)可能会返回包含你的docs文件夹的路径。然后，你可以相应地修改路径以访问.html文件。

- Mia

Answer 3

通常，文档是独立于程序包部署的。例如，pandas存储库（其中包括.rst文件中文档的源代码）存储在Github上，但构建好的文档可在其自己的URL上获取。

- bluprince13