Python Path Issues with Sphinx?

Ed May 0
Viewed 32

I'm running into a lot of trouble trying to use Sphinx autodoc for a python package, and I think the issue is a path one, but I'm not sure how to solve? Wondering if anyone might know?

I'm trying it out with just a super basic module setup with a single main.py inside of 'my_project' that looks like: main.py contents and file structure

In both cases below, I have just a basic conf.py and index.rst file: conf.py and index.rst file contents

Scenario 1 (works fine)

When I use the sphinx-quickstart command to build out the folder tree and specify 'N' when asks if I want to separate source and build directories, it seems to all work fine and I am able to successfully build the html and it finds and reads my_project.main without issue. In this case, I get a folder tree that looks like:

.
├── docs
│   ├── build
│   ├──_static
│   ├──_templates
│   ├──conf.py
│   └──index.rst
└── my_project
    └── main

Scenario 2 (not working)

However: When I use the sphinx-quickstart command to build out the folder tree and specify 'Y' when it asks about separating source and build, now I get a nicer more ordered folder tree within my ./docs. So now I have:

.
├── docs
│   ├── build
│   └── source
│        ├──_static
│        ├──_templates
│        ├──conf.py
│        └──index.rst
└── my_project
    └── main

But the nesting of the conf.py (I think?) seems to be causing path trouble? Now if I try and build the html, I get an import error:

WARNING: autodoc: failed to import module 'main' from module 'my_project'; 
the following exception was raised:
No module named 'my_project'

So it seems that the conf.py is not probably finding and adding the top-level path in this case?

So, I wonder:

  1. How can I add a folder 2 levels 'up' from current to the sys.path? I can get one level 'up' using .. but ... does not work to go up two? It does not work when I try something like: sys.path.insert(0, os.path.abspath('...')) # three dots does doesn't work?
  2. Am I missing something else here? how should I be using the 'nested' sphinx-quickstart setup to properly find my modules using autodoc?
autodoc python-sphinx path python
1 Answers

As you may have surmised, autodoc needs to be able to import your code in order to make your docs. There are two ways to do this:

  1. The easy way is to edit the sys.path.insert line in conf.py. You almost had this right: instead of ..., it should be ../...

  2. The better way (in my opinion) is to (i) install your package in a virtual environment and (ii) install/run sphinx in that same environment. This way, you don't need to mess with the import path at all. Installing your code also makes it a lot easier to share/reuse (even if only between other scripts on your machine).

    If you don't know how to do this, I'd recommend looking into a tool called flit. The whole process should look something like this (although note that I haven't actually tested any of these commands):

    # Create a `pyproject.toml` file:
flit init

# Create a new virtual environment
python -m venv sphinx-env
. sphinx-env/bin/activate

# Install your package and sphinx 
pip install . sphinx

# Run sphinx
cd docs
make html
Kale Kundert0
Related