Commits to the planetary-data-engine repo cannot be merged due to CI/CD build error related to sphinx

Checked for duplicates

Yes - I've already checked

🐛 Describe the bug

When I commit to my own branch (sinequa-api-notebook) in the planetary-data-engine repo the automated CI/CD workflow gets the following error: error: invalid command 'build_sphinx'. The relevant lines in the log are:

docs: commands[0]> python setup.py build_sphinx
/home/runner/work/planetary-data-engine/planetary-data-engine/.tox/docs/lib/python3.9/site-packages/setuptools/config/setupcfg.py:293: _DeprecatedConfig: Deprecated config in `setup.cfg`
!!

        ********************************************************************************
        The namespace_packages parameter is deprecated, consider using implicit namespaces instead (PEP 420).

        See https://setuptools.pypa.io/en/latest/userguide/declarative_config.html for details.
        ********************************************************************************

!!
  parsed = self.parsers.get(option_name, lambda x: x)(value)
usage: setup.py [global_opts] cmd1 [cmd1_opts] [cmd2 [cmd2_opts] ...]
   or: setup.py --help [cmd1 cmd2 ...]
   or: setup.py --help-commands
   or: setup.py cmd --help

error: invalid command 'build_sphinx'
docs: exit 1 (0.32 seconds) /home/runner/work/planetary-data-engine/planetary-data-engine> python setup.py build_sphinx pid=2131

🕵️ Expected behavior

I expected the commit to have no errors. This error is in a part of the repo that I don't touch.

📜 To Reproduce

Push any commit to a branch in the repo.
Wait a few minutes for an email referencing Run failed: Branch integraion testing
Click the link in the email or navigate directly to view the workflow run. Check the logs carefully to find the error.

🖥 Environment Info

git version 2.39.3
Operating System: MacOSX Venture 13.6

📚 Version of Software Used

git version 2.39.3

🩺 Test Data / Additional context

No response

🦄 Related requirements

No response

⚙️ Engineering Details

No response

Hi @jjacob7734, to quickly get some docs built, try:

sphinx-build docs/source docs/build
open docs/build/index.html

However, the real problem is that it looks like Sphinx is not installing a setup.py extension command to build the docs. This is because in your setup.cfg you have sphinx listed without a version pin, which means "grab me the latest".

The Python template repo uses sphinx~=3.2.1. If I add that to your setup.cfg, then I get python setup.py build_sphinx—but it fails because the Jinja2 dependency is also too high. If I also add Jinja2<3.1, then python setup.py build_sphinx works fine.

In fact, you'll probably want to pin all your dev dependencies in order to avoid the version confusion security vulnerability. Here are the correct pins to use from the Python template repo:

black~=23.7.0
flake8~=6.1.0
flake8-bugbear~=23.7.10
flake8-docstrings~=1.7.0
pep8-naming~=0.13.3
mypy~=1.5.1
pydocstyle~=6.3.0
coverage~=7.3.0
pytest~=7.4.0
pytest-cov~=4.1.0
pytest-watch~=4.2.0
pytest-xdist~=3.3.1
pre-commit~=3.3.3
sphinx~=3.2.1
sphinx-rtd-theme~=0.5.0
tox~=4.11.0
types-setuptools~=68.1.0.0
Jinja2<3.1

@nutjob4life committed the fix for this to the sinequa-api-notebook branch to be merged.

Hi @jjacob7734, to quickly get some docs built, try:
sphinx-build docs/source docs/build
open docs/build/index.html
However, the real problem is that it looks like Sphinx is not installing a setup.py extension command to build the docs. This is because in your setup.cfg you have sphinx listed without a version pin, which means "grab me the latest".

The Python template repo uses sphinx~=3.2.1. If I add that to your setup.cfg, then I get python setup.py build_sphinx—but it fails because the Jinja2 dependency is also too high. If I also add Jinja2<3.1, then python setup.py build_sphinx works fine.

In fact, you'll probably want to pin all your dev dependencies in order to avoid the version confusion security vulnerability. Here are the correct pins to use from the Python template repo:
black~=23.7.0
flake8~=6.1.0
flake8-bugbear~=23.7.10
flake8-docstrings~=1.7.0
pep8-naming~=0.13.3
mypy~=1.5.1
pydocstyle~=6.3.0
coverage~=7.3.0
pytest~=7.4.0
pytest-cov~=4.1.0
pytest-watch~=4.2.0
pytest-xdist~=3.3.1
pre-commit~=3.3.3
sphinx~=3.2.1
sphinx-rtd-theme~=0.5.0
tox~=4.11.0
types-setuptools~=68.1.0.0
Jinja2<3.1

NASA-PDS / planetary-data-engine