How would the end-user access the Sphinx generated documentation for a Python package?

Question

I have developed a package in python, and I have created documentation for it using Sphinx.

The relevant part of the folder structure is shown below:

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

The package will be hosted at some location in the LAN that's referred to by PYTHONPATH. My end user will be accessing my package with just import my_package. They wouldn't know where the documentation (or the package for that matter) is located. Using help(my_package) is only going to show the user the documentation within the module.

So, I am wondering how to allow my end-user to access the index.html file? I thought of coding in a method that opens the html file from a specified location, but I didn't like the idea of hardcoding in a path. Is there a standard way of doing this?

Why not add the path to Sphinx-Documentation to the docstring of the module? — Christian Sauer, Mar 31 '17 at 11:15
@ChristianSauer I thought of that, but since the docs are part of the package, I was hoping that there'd be some way of allowing the user to call up the ``index.html`` from wherever the package is installed. — bluprince13, Mar 31 '17 at 14:02
Honsetly, what stops you from deploying the docs with your package? I have done just that for one of our internal packages - sure it would not do it for a public package, but for our internal package, it was the easiest option to get the docs deployed — Christian Sauer, Mar 31 '17 at 14:56
@ChristianSauer, I will be deploying the docs with my package, but I just want to avoid telling the user: go to wherever you installed the package, and look in docs > _build > html and open the index.html file to access the documentation. That doesn't seem very neat... — bluprince13, Mar 31 '17 at 15:00
What kind of editor do you use? If pycharm, you can add additional doc sources for packages. If not, the easiest is to add an url to the docstrings of the package, methods and classes. it's not uncommon, numpy does exactly this. — Christian Sauer, Mar 31 '17 at 15:24

score 1 · Answer 1 · edited May 23 '17 at 12:25

To expand on @pkqxdd-s suggestion:

You can easily obtain the path to documentation within modules of 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

Now you could add the path to my_module or my_package docstring, so that users who call help(my_module) will get something like

... 
# original my_module docstring
...

See sphinx docs at <path to your index>

See this question to learn how to add the path from get_docs_index_path() to the docstring.

score 0 · Answer 2 · edited May 23 '17 at 12:34

So if your only concern is you don't know where your module will be installed, you can figure that out by calling your_module.__file__(see this post). In addition, you can also make use of os.path module. For example, calling os.path.dirname(your_module.__file__) may return the path to the folder where your docs folder is. You can then modify the path accordingly to access the .html file.

score 0 · Accepted Answer · answered Oct 22 '17 at 20:26

0

Generally, documentation is deployed separately to the package. For example the pandas repository (which includes the source code for the documentation in .rst files) is held in Github, but the built documentation is available at its own url.

answered Oct 22 '17 at 20:26

bluprince13

4,607
12
44
91

How would the end-user access the Sphinx generated documentation for a Python package?

3 Answers3