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

Question

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

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

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

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

所以，我想知道如何让我的最终用户访问index.html文件？我想过在一个从指定位置打开html文件的方法编码，但我不喜欢在路径中硬编码的想法。有没有一种标准的方法呢？

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 docstring的路径，以便拨打help(my_module)的用户可以获得类似

的内容

... 
# original my_module docstring
...

See sphinx docs at <path to your index>

请参阅this question，了解如何将get_docs_index_path()的路径添加到文档字符串。

Answer 2

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

Answer 3

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