Fix doc warnings

[anmol-janamatti]

This pull request addresses the documentation build limitations described in #887. It enables compatibility with modern Sphinx and Docutils versions and significantly reduces build warnings.

Changes:

Relaxed Dependencies: Updated pyproject.toml to remove strict upper version bounds for sphinx (<8) and docutils (<0.19). The documentation now builds successfully with Sphinx 9.0.4 and Docutils 0.22.3.

Fixed Build Error: Disabled the sphinx_autodoc_defaultargs extension in docs/conf.py as it caused an "invalid signature" error with newer Sphinx versions.

Fixed Import Warnings: Added the inner radis package directory to sys.path in docs/conf.py. This resolved ~90 "Failed to import module" warnings where Sphinx could not locate submodules like radis.misc or radis.db.

Results:

Build is now successful with latest dependencies.
Build warnings reduced from 123 to 33.
Fixes #887

[minouHub]

Hello,
You failed the tests with write access. This is normal, only admin can run them. (This should be moved to a non mandatory test at some point). However, you should sort the linting: https://radis.readthedocs.io/en/latest/dev/developer.html#code-style-and-linting
Also, there are still some warnings, do you think you can sort them? https://app.readthedocs.org/projects/radis/builds/30600297/

Import warning

WARNING: Failed to import api.
ImportError: attempted relative import beyond top-level package

Font warning

indfont: Generic family 'sans-serif' not found because none of the following families were found: Helvetica, Bitstream Vera Sans, Lucida Grande, Verdana, Geneva, Lucid, Arial, Avant Garde, sans-serif

[anmol-janamatti]

Hi,

Thank you so much for reviewing and sharing these details.

I understand that the write-access tests failed due to permission restrictions, and that’s completely fine. I will take care of the linting issues and make sure the code fully aligns with the style guidelines mentioned here: https://radis.readthedocs.io/en/latest/dev/developer.html#code-style-and-linting

I will also look into the remaining warnings from the latest ReadTheDocs build: https://app.readthedocs.org/projects/radis/builds/30600297/

Specifically, I will address:
• The import warning by correcting the relative import path for api
• The font warning by updating the Matplotlib fallback configuration

Thank you again for your guidance and patience — I really appreciate it.
I’ll make the necessary updates and push the changes shortly.

[anmol-janamatti]

hi @minouHub
i have fixed the linting and warnings(import and font). please review

[minouHub]

Still found a lot of warnings, see the latest build: https://app.readthedocs.org/projects/radis/builds/30630802/

Import warning

Now that you started, do you think you could catch the others at the start of the log? There also a bunch near line 800 of the log

Example:

File "/home/docs/checkouts/readthedocs.org/user_builds/radis/conda/889/lib/python3.13/site-packages/sphinx/ext/autodoc/_dynamic/_importer.py", line 131, in _import_from_module_and_path
 module = _import_module(module_name, try_reload=True)
File "/home/docs/checkouts/readthedocs.org/user_builds/radis/conda/889/lib/python3.13/site-packages/sphinx/ext/autodoc/_dynamic/_importer.py", line 218, in _import_module
raise ModuleNotFoundError(msg, name=modname)  # NoQA: TRY301

Font

This message is still often present.
findfont: Generic family 'sans-serif' not found because none of the following families were found: Helvetica, Bitstream Vera Sans, Lucida Grande, Verdana, Geneva, Lucid, Arial, Avant Garde, sans-serif

Many docutils warnings

There are a lot of warnings/errors that prevent proper identification of actual problems. Notably:

• ERROR: Unexpected section title.
• WARNING: Block quote ends without a blank line; unexpected unindent. [docutils]
• WARNING: Inline interpreted text or phrase reference start-string without end-string. [docutils]
• WARNING: Inline emphasis start-string without end-string.
• ERROR: Unexpected indentation.
• ERROR: Undefined substitution referenced: "m".
  ... and I'm probably missing a lot. Do you think there is an automated way (via AI maybe) to clean all the files from these minor issues?

[minouHub]

Is it useful to keep this comment?

[minouHub]

Interesting summary but ... why do you keep this file orphan?

[minouHub]

Hello,
Could you rebase on develop? A fix in #896 should help having all the tests in green.

[anmol-janamatti]

Hmm Yeah @minouHub

[minouHub]

Hello,
Could you merge/rebase on develop and consider my comment?

[minouHub]

Hello,
Do you still want to work on this issue? If not, I'm closing after the 1st of March

[minouHub]

Closed due to inactivity