search

cta-observatory / cta-lstchain

LST prototype testbench chain
https://cta-observatory.github.io/cta-lstchain/
BSD 3-Clause "New" or "Revised" License
26 stars 77 forks source link

Warnings in docs can make sphinx build fail #1304

Closed morcuended closed 1 month ago

morcuended commented 1 month ago

Currently, Sphinx generates 14 warnings when building the docs. Sphinx treats these warnings as errors, and if the number keeps increasing, the docs' build can fail as happened in https://github.com/cta-observatory/cta-lstchain/actions/runs/11231362777/job/31224128576

While they are not problematic for the code, I think they indicate problems with the code.

I leave them here to fix them at some point.

WARNING: autodoc: failed to import function 'parse_cfg_bytestring' from module 'lstchain.io.io'; the following exception was raised:
Traceback (most recent call last):
  File "/Users/dmorcuende/.local/miniconda/envs/lstchain-tmp/lib/python3.12/site-packages/sphinx/util/inspect.py", line 374, in safe_getattr
    return getattr(obj, name, *defargs)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
AttributeError: module 'lstchain.io.io' has no attribute 'parse_cfg_bytestring'

The above exception was the direct cause of the following exception:

Traceback (most recent call last):
  File "/Users/dmorcuende/.local/miniconda/envs/lstchain-tmp/lib/python3.12/site-packages/sphinx/ext/autodoc/importer.py", line 209, in import_object
    obj = attrgetter(obj, mangled_name)
          ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/dmorcuende/.local/miniconda/envs/lstchain-tmp/lib/python3.12/site-packages/sphinx/ext/autodoc/__init__.py", line 329, in get_attr
    return autodoc_attrgetter(self.env.app, obj, name, *defargs)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/dmorcuende/.local/miniconda/envs/lstchain-tmp/lib/python3.12/site-packages/sphinx/ext/autodoc/__init__.py", line 2844, in autodoc_attrgetter
    return safe_getattr(obj, name, *defargs)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/dmorcuende/.local/miniconda/envs/lstchain-tmp/lib/python3.12/site-packages/sphinx/util/inspect.py", line 390, in safe_getattr
    raise AttributeError(name) from exc
AttributeError: parse_cfg_bytestring

WARNING: autodoc: failed to import function 'interpolate_al_cuts' from module 'lstchain.high_level.interpolate'; the following exception was raised:
Traceback (most recent call last):
  File "/Users/dmorcuende/.local/miniconda/envs/lstchain-tmp/lib/python3.12/site-packages/sphinx/util/inspect.py", line 374, in safe_getattr
    return getattr(obj, name, *defargs)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
AttributeError: module 'lstchain.high_level.interpolate' has no attribute 'interpolate_al_cuts'. Did you mean: 'interpolate_cuts'?

The above exception was the direct cause of the following exception:

Traceback (most recent call last):
  File "/Users/dmorcuende/.local/miniconda/envs/lstchain-tmp/lib/python3.12/site-packages/sphinx/ext/autodoc/importer.py", line 209, in import_object
    obj = attrgetter(obj, mangled_name)
          ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/dmorcuende/.local/miniconda/envs/lstchain-tmp/lib/python3.12/site-packages/sphinx/ext/autodoc/__init__.py", line 329, in get_attr
    return autodoc_attrgetter(self.env.app, obj, name, *defargs)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/dmorcuende/.local/miniconda/envs/lstchain-tmp/lib/python3.12/site-packages/sphinx/ext/autodoc/__init__.py", line 2844, in autodoc_attrgetter
    return safe_getattr(obj, name, *defargs)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/dmorcuende/.local/miniconda/envs/lstchain-tmp/lib/python3.12/site-packages/sphinx/util/inspect.py", line 390, in safe_getattr
    raise AttributeError(name) from exc
AttributeError: interpolate_al_cuts

WARNING: autodoc: failed to import function 'interpolate_gh_cuts' from module 'lstchain.high_level.interpolate'; the following exception was raised:
Traceback (most recent call last):
  File "/Users/dmorcuende/.local/miniconda/envs/lstchain-tmp/lib/python3.12/site-packages/sphinx/util/inspect.py", line 374, in safe_getattr
    return getattr(obj, name, *defargs)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
AttributeError: module 'lstchain.high_level.interpolate' has no attribute 'interpolate_gh_cuts'. Did you mean: 'interpolate_cuts'?

The above exception was the direct cause of the following exception:

Traceback (most recent call last):
  File "/Users/dmorcuende/.local/miniconda/envs/lstchain-tmp/lib/python3.12/site-packages/sphinx/ext/autodoc/importer.py", line 209, in import_object
    obj = attrgetter(obj, mangled_name)
          ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/dmorcuende/.local/miniconda/envs/lstchain-tmp/lib/python3.12/site-packages/sphinx/ext/autodoc/__init__.py", line 329, in get_attr
    return autodoc_attrgetter(self.env.app, obj, name, *defargs)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/dmorcuende/.local/miniconda/envs/lstchain-tmp/lib/python3.12/site-packages/sphinx/ext/autodoc/__init__.py", line 2844, in autodoc_attrgetter
    return safe_getattr(obj, name, *defargs)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/dmorcuende/.local/miniconda/envs/lstchain-tmp/lib/python3.12/site-packages/sphinx/util/inspect.py", line 390, in safe_getattr
    raise AttributeError(name) from exc
AttributeError: interpolate_gh_cuts

WARNING: autodoc: failed to import function 'tune_nsb_on_waveform' from module 'lstchain.image.modifier'; the following exception was raised:
Traceback (most recent call last):
  File "/Users/dmorcuende/.local/miniconda/envs/lstchain-tmp/lib/python3.12/site-packages/sphinx/util/inspect.py", line 374, in safe_getattr
    return getattr(obj, name, *defargs)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
AttributeError: module 'lstchain.image.modifier' has no attribute 'tune_nsb_on_waveform'

The above exception was the direct cause of the following exception:

Traceback (most recent call last):
  File "/Users/dmorcuende/.local/miniconda/envs/lstchain-tmp/lib/python3.12/site-packages/sphinx/ext/autodoc/importer.py", line 209, in import_object
    obj = attrgetter(obj, mangled_name)
          ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/dmorcuende/.local/miniconda/envs/lstchain-tmp/lib/python3.12/site-packages/sphinx/ext/autodoc/__init__.py", line 329, in get_attr
    return autodoc_attrgetter(self.env.app, obj, name, *defargs)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/dmorcuende/.local/miniconda/envs/lstchain-tmp/lib/python3.12/site-packages/sphinx/ext/autodoc/__init__.py", line 2844, in autodoc_attrgetter
    return safe_getattr(obj, name, *defargs)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/dmorcuende/.local/miniconda/envs/lstchain-tmp/lib/python3.12/site-packages/sphinx/util/inspect.py", line 390, in safe_getattr
    raise AttributeError(name) from exc
AttributeError: tune_nsb_on_waveform

/Users/dmorcuende/Software/CTA/LST/cta-lstchain/docs/api/lstchain.tools.lstchain_create_dl3_file.DataReductionFITSWriter.rst:11: WARNING: autosummary: failed to import DataReductionFITSWriter.final_irf_file.
Possible hints:
* ModuleNotFoundError: No module named 'lstchain.tools.lstchain_create_dl3_file.DataReductionFITSWriter'; 'lstchain.tools.lstchain_create_dl3_file' is not a package
* KeyError: 'DataReductionFITSWriter'
* AttributeError: type object 'DataReductionFITSWriter' has no attribute 'final_irf_file'
* PycodeError: no source found for module 'builtins'
* ModuleNotFoundError: No module named 'DataReductionFITSWriter'
* AttributeError: type object 'DataReductionFITSWriter' has no attribute 'DataReductionFITSWriter'
WARNING: autodoc: failed to import attribute 'DataReductionFITSWriter.final_irf_file' from module 'lstchain.tools.lstchain_create_dl3_file'; the following exception was raised:
Traceback (most recent call last):
  File "/Users/dmorcuende/.local/miniconda/envs/lstchain-tmp/lib/python3.12/site-packages/sphinx/ext/autodoc/importer.py", line 209, in import_object
    obj = attrgetter(obj, mangled_name)
          ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/dmorcuende/.local/miniconda/envs/lstchain-tmp/lib/python3.12/site-packages/sphinx/ext/autodoc/__init__.py", line 329, in get_attr
    return autodoc_attrgetter(self.env.app, obj, name, *defargs)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/dmorcuende/.local/miniconda/envs/lstchain-tmp/lib/python3.12/site-packages/sphinx/ext/autodoc/__init__.py", line 2842, in autodoc_attrgetter
    return func(obj, name, *defargs)
           ^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/dmorcuende/.local/miniconda/envs/lstchain-tmp/lib/python3.12/site-packages/sphinx_automodapi/autodoc_enhancements.py", line 61, in type_object_attrgetter
    return getattr(obj, attr, *defargs)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
AttributeError: type object 'DataReductionFITSWriter' has no attribute 'final_irf_file'

looking for now-outdated files... none found
pickling environment... done
checking consistency... /Users/dmorcuende/Software/CTA/LST/cta-lstchain/docs/api/lstchain.high_level.interpolate.interpolate_al_cuts.rst: WARNING: document isn't included in any toctree
/Users/dmorcuende/Software/CTA/LST/cta-lstchain/docs/api/lstchain.high_level.interpolate.interpolate_gh_cuts.rst: WARNING: document isn't included in any toctree
/Users/dmorcuende/Software/CTA/LST/cta-lstchain/docs/api/lstchain.image.modifier.tune_nsb_on_waveform.rst: WARNING: document isn't included in any toctree
/Users/dmorcuende/Software/CTA/LST/cta-lstchain/docs/api/lstchain.io.io.parse_cfg_bytestring.rst: WARNING: document isn't included in any toctree
/Users/dmorcuende/Software/CTA/LST/cta-lstchain/docs/notebooks.rst: WARNING: document isn't included in any toctree
morcuended commented 1 month ago

I realized that most of these warnings come from old previously built documentation. With a clean building, there is only one warning remaining:

/Users/dmorcuende/Software/CTA/LST/cta-lstchain/docs/notebooks.rst: WARNING: document isn't included in any toctree

that will be included in PR #1091.

Closing this.