sphinx builds locally but not via github action

[ablot]

Describe the bug
A clear and concise description of what the bug is. If possible, please submit a Minimal Reproducible Example.

After starting my repository, sphinx-build docs/source docs/build works locally on my machine (in my conda environement) but when pushing I get import errors. For instance:

Extension error (sphinx.ext.autosummary):
Handler <function process_generate_options at 0x7fecb6b64cc0> for event 'builder-inited' threw an exception (exception: no module named image_tools.registration.masked_phase_correlation)
Error: Process completed with exit code 2.

It's not a typo or naming error, any import from my repo (image_tools) fails, as if sphinx was running from an environment before installing the package. Do I need to add steps to configure?

To Reproduce
Please enter full details of how to reproduce this bug.

Run the cookiecutter and push to main

Expected behaviour
A clear and concise description of what you expected to happen.

Successful build

[niksirbi]

Hi @ablot, thanks for raising this!
I think I've encountered something like this before. Here is what I think is happening:

When GitHub actions build the docs, they do it in a separate environment in which they install the requirements that are specific to the docs, i.e. those defined in docs/requirements.txt. Your own package, and its requirements (the ones defined in pyproject.toml) are not automatically installed during this process.

To solve your issue, you'd have to add -e . to the docs/requirements.txt file (see example). This will force the relevant GitHub Actions to also install your own package (from the repo source) in the environment in which the docs are built.

Please do let me know if this solution works for you. If yes, we will make sure to adjust the README or even include -e . in docs/requirements.txt by default.

[ablot]

Indeed! Success ✅
Thanks!

[niksirbi]

@adamltyson what do you think about including -e . to the docs/requirements.txt file by default?

[adamltyson]

I didn't know you could do this, but if it works, sounds good. Would be worth documenting it though in case it causes any unforeseen issues.

[niksirbi]

Agreed. In theory, you don't need it if your are not building API docs, but I guess most people will be using it in this way.