[FDS-2449] Lock sphinx version and update poetry.lock

[jaymedina]

problem

The ReadTheDocs page for schematic was not rendering its contents properly. I was able to re-create the error when starting a new environment from scratch with sphinx v7.4.7. I found that there was no version locked for sphinx which led to the poetry.lock file updating with v7.4.7. This version caused the issue with the documentation build. While the reason isn't clear, I suspect it has something to do with v7.4.7 not working with v4.4.0 of sphinx-click.

solution

• Specify a sphinx version in the pyproject.toml file, which is used to create the poetry.lock file
• Lock the 4.4.0 version of sphinx-click in the pyproject.toml since we know that works with the new specified version of sphinx. This is the package that the ci_references.rtd needs in order to render properly.
• Rerun the lock file after

testing

Creating a fresh environment with the new poetry.lock file and building the docs locally now results in a properly rendered CLI Reference page.

Here are the steps to build the docs locally off these changes:

1. Create a fresh environment

pyenv virtualenv 3.9 rtd-test-env
pyenv activate rtd-test-env

2. Follow the installation steps from the last passing RTD build (do this in the root of the schematic repository while checked into this branch)

python -m pip install --upgrade --no-cache-dir pip setuptools
pip install poetry==1.3.0
poetry config virtualenvs.create false
poetry install --with doc

3. Build the documentation (the command below assumes you're in the root of the repository)

sphinx-build -b html docs/source _build/html

Result:

[thomasyu888]

This should fix this trivy issue: #1531

[BryanFauble]

Thanks for the update!

[thomasyu888]

Do you have to change the installation instructions in .readthedocs.yml for this to work? This worked for me , but im not sure that's the right approach (maybe it is for the short term)

poetry install --all-extras

I'm getting

Running Sphinx v7.3.7
loading translations [English]... not available for built-in messages
making output directory... done
WARNING: html_static_path entry '_static' does not exist
building [mo]: targets for 0 po files that are out of date
writing output... 
building [html]: targets for 2 source files that are out of date
updating environment: [new config] 2 added, 0 changed, 0 removed
reading sources... [100%] index
/Users/tyu/sage/schematic/docs/source/cli_reference.rst:5: ERROR: Failed to import "main" from "schematic.__main__". The following exception was raised:
Traceback (most recent call last):
  File "/Users/tyu/anaconda3/envs/schematic/lib/python3.10/site-packages/sphinx_click/ext.py", line 403, in _load_module
    mod = __import__(module_name, globals(), locals(), [attr_name])
  File "/Users/tyu/sage/schematic/schematic/__init__.py", line 8, in <module>
    from opentelemetry.instrumentation.flask import FlaskInstrumentor
ModuleNotFoundError: No module named 'opentelemetry.instrumentation.flask'
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
copying assets... copying static files... done
copying extra files... done
done
writing output... [100%] index
generating indices... genindex done
writing additional pages... search done
dumping search index in English (code: en)... done
dumping object inventory... done
build succeeded, 2 warnings.

The HTML pages are in _build/html.

I added a deployment here: https://schematicpy.readthedocs.io/en/fds-2449-fix-rtd/cli_reference.html. which will auto build your branch when you make changes

[jaymedina]

Do you have to change the installation instructions in .readthedocs.yml for this to work?

No, I changed it so I'd have the opportunity to explain the groups being downloaded with the command. I thought this would be better than doing an --all-extras, which makes the process feel more opaque (you don't know what these extras are, or what they're for).

[thomasyu888]

No, I changed it so I'd have the opportunity to explain the groups being downloaded with the command. I thought this would be better than doing an --all-extras, which makes the process feel more opaque (you don't know what these extras are, or what they're for).

@jaymedina Makes sense, lets confirm that this builds: https://schematicpy.readthedocs.io/en/fds-2449-fix-rtd/cli_reference.html. You can log into readthedocs to view the schematicpy builds and logs. We may want to add dependencies then to the doc.dependencies section if there are still ones missing.

[thomasyu888]

🔥 LGTM!

[thomasyu888]

@jaymedina Can you make sure the tests run locally? My concern is that there are dependency version updates, so the 3.10 tests not passing is unfortunate..

Otherwise, I approve of this!

The tests passed (i just re-ran them)

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarCloud