search

raphaelquast / EOmaps

A library to create interactive maps of geographical datasets
https://eomaps.readthedocs.io/
BSD 3-Clause "New" or "Revised" License
339 stars 25 forks source link

Warnings during documentation build #212

Closed banesullivan closed 11 months ago

banesullivan commented 11 months ago

When build the docs, I recommend using SPHINXOPTS="-W" to fail on warnings that might suggest broken references, missing pages, etc. My full build log:

``` $ make html ─╯ Running Sphinx v7.2.6 [autosummary] generating autosummary for: reference.rst building [mo]: targets for 0 po files that are out of date writing output... building [html]: targets for 770 source files that are out of date updating environment: [new config] 770 added, 0 changed, 0 removed ... unable to activate PyQt5 backend... defaulting to 'tkinter' reading sources... [100%] substitutions /home/bane/Software/pyopensci/reviews/EOmaps/docs/generated/eomaps.rst:35: WARNING: autosummary: stub file not found 'eomaps.eomaps.utilities'. Check your autosummary_generate setting. /home/bane/Software/pyopensci/reviews/EOmaps/eomaps/annotation_editor.py:docstring of eomaps.annotation_editor.AnnotationEditor.print_code:46: ERROR: Unexpected indentation. /home/bane/Software/pyopensci/reviews/EOmaps/eomaps/annotation_editor.py:docstring of eomaps.annotation_editor.AnnotationEditor.print_code:47: WARNING: Block quote ends without a blank line; unexpected unindent. /home/bane/Software/pyopensci/reviews/EOmaps/eomaps/eomaps.py:docstring of eomaps.eomaps.Maps.CLASSIFIERS:1: WARNING: duplicate object description of eomaps.eomaps.Maps.CLASSIFIERS, other instance in generated/eomaps.eomaps.Maps, use :no-index: for one of them /home/bane/.pyenv/versions/3.11.6/envs/eomaps/lib/python3.11/site-packages/matplotlib/pyplot.py:docstring of matplotlib.pyplot.savefig:22: ERROR: Unknown interpreted text role "rc". /home/bane/.pyenv/versions/3.11.6/envs/eomaps/lib/python3.11/site-packages/matplotlib/pyplot.py:docstring of matplotlib.pyplot.savefig:49: ERROR: Unknown interpreted text role "rc". /home/bane/.pyenv/versions/3.11.6/envs/eomaps/lib/python3.11/site-packages/matplotlib/pyplot.py:docstring of matplotlib.pyplot.savefig:52: ERROR: Unknown interpreted text role "rc". /home/bane/.pyenv/versions/3.11.6/envs/eomaps/lib/python3.11/site-packages/matplotlib/pyplot.py:docstring of matplotlib.pyplot.savefig:74: ERROR: Unknown interpreted text role "rc". /home/bane/.pyenv/versions/3.11.6/envs/eomaps/lib/python3.11/site-packages/matplotlib/pyplot.py:docstring of matplotlib.pyplot.savefig:79: ERROR: Unknown interpreted text role "rc". /home/bane/.pyenv/versions/3.11.6/envs/eomaps/lib/python3.11/site-packages/matplotlib/pyplot.py:docstring of matplotlib.pyplot.savefig:82: ERROR: Unknown interpreted text role "rc". /home/bane/.pyenv/versions/3.11.6/envs/eomaps/lib/python3.11/site-packages/matplotlib/pyplot.py:docstring of matplotlib.pyplot.savefig:85: ERROR: Unknown interpreted text role "rc". /home/bane/.pyenv/versions/3.11.6/envs/eomaps/lib/python3.11/site-packages/matplotlib/gridspec.py:docstring of matplotlib.gridspec.GridSpec.update:3: ERROR: Unknown interpreted text role "rc". /home/bane/.pyenv/versions/3.11.6/envs/eomaps/lib/python3.11/site-packages/matplotlib/figure.py:docstring of matplotlib.figure.FigureBase.text:13: ERROR: Unknown interpreted text role "rc". /home/bane/.pyenv/versions/3.11.6/envs/eomaps/lib/python3.11/site-packages/matplotlib/pyplot.py:docstring of matplotlib.pyplot.savefig:22: ERROR: Unknown interpreted text role "rc". /home/bane/.pyenv/versions/3.11.6/envs/eomaps/lib/python3.11/site-packages/matplotlib/pyplot.py:docstring of matplotlib.pyplot.savefig:49: ERROR: Unknown interpreted text role "rc". /home/bane/.pyenv/versions/3.11.6/envs/eomaps/lib/python3.11/site-packages/matplotlib/pyplot.py:docstring of matplotlib.pyplot.savefig:52: ERROR: Unknown interpreted text role "rc". /home/bane/.pyenv/versions/3.11.6/envs/eomaps/lib/python3.11/site-packages/matplotlib/pyplot.py:docstring of matplotlib.pyplot.savefig:74: ERROR: Unknown interpreted text role "rc". /home/bane/.pyenv/versions/3.11.6/envs/eomaps/lib/python3.11/site-packages/matplotlib/pyplot.py:docstring of matplotlib.pyplot.savefig:79: ERROR: Unknown interpreted text role "rc". /home/bane/.pyenv/versions/3.11.6/envs/eomaps/lib/python3.11/site-packages/matplotlib/pyplot.py:docstring of matplotlib.pyplot.savefig:82: ERROR: Unknown interpreted text role "rc". /home/bane/.pyenv/versions/3.11.6/envs/eomaps/lib/python3.11/site-packages/matplotlib/pyplot.py:docstring of matplotlib.pyplot.savefig:85: ERROR: Unknown interpreted text role "rc". /home/bane/.pyenv/versions/3.11.6/envs/eomaps/lib/python3.11/site-packages/matplotlib/gridspec.py:docstring of matplotlib.gridspec.GridSpec.update:3: ERROR: Unknown interpreted text role "rc". /home/bane/.pyenv/versions/3.11.6/envs/eomaps/lib/python3.11/site-packages/matplotlib/figure.py:docstring of matplotlib.figure.FigureBase.text:13: ERROR: Unknown interpreted text role "rc". /home/bane/Software/pyopensci/reviews/EOmaps/eomaps/mapsgrid.py:docstring of eomaps.mapsgrid.MapsGrid.f:1: WARNING: duplicate object description of eomaps.mapsgrid.MapsGrid.f, other instance in generated/eomaps.mapsgrid.MapsGrid, use :no-index: for one of them /home/bane/.pyenv/versions/3.11.6/envs/eomaps/lib/python3.11/site-packages/matplotlib/pyplot.py:docstring of matplotlib.pyplot.savefig:22: ERROR: Unknown interpreted text role "rc". /home/bane/.pyenv/versions/3.11.6/envs/eomaps/lib/python3.11/site-packages/matplotlib/pyplot.py:docstring of matplotlib.pyplot.savefig:43: ERROR: Unknown interpreted text role "rc". /home/bane/.pyenv/versions/3.11.6/envs/eomaps/lib/python3.11/site-packages/matplotlib/pyplot.py:docstring of matplotlib.pyplot.savefig:46: ERROR: Unknown interpreted text role "rc". /home/bane/.pyenv/versions/3.11.6/envs/eomaps/lib/python3.11/site-packages/matplotlib/pyplot.py:docstring of matplotlib.pyplot.savefig:68: ERROR: Unknown interpreted text role "rc". /home/bane/.pyenv/versions/3.11.6/envs/eomaps/lib/python3.11/site-packages/matplotlib/pyplot.py:docstring of matplotlib.pyplot.savefig:73: ERROR: Unknown interpreted text role "rc". /home/bane/.pyenv/versions/3.11.6/envs/eomaps/lib/python3.11/site-packages/matplotlib/pyplot.py:docstring of matplotlib.pyplot.savefig:76: ERROR: Unknown interpreted text role "rc". /home/bane/.pyenv/versions/3.11.6/envs/eomaps/lib/python3.11/site-packages/matplotlib/pyplot.py:docstring of matplotlib.pyplot.savefig:79: ERROR: Unknown interpreted text role "rc". /home/bane/.pyenv/versions/3.11.6/envs/eomaps/lib/python3.11/site-packages/matplotlib/gridspec.py:docstring of matplotlib.gridspec.GridSpec.update:3: ERROR: Unknown interpreted text role "rc". looking for now-outdated files... none found pickling environment... done checking consistency... /home/bane/Software/pyopensci/reviews/EOmaps/docs/api.rst: WARNING: document isn't included in any toctree /home/bane/Software/pyopensci/reviews/EOmaps/docs/generated/eomaps.utilities.rst: WARNING: document isn't included in any toctree done preparing documents... done copying assets... copying static files... done copying extra files... done done writing output... [100%] substitutions /home/bane/.pyenv/versions/3.11.6/envs/eomaps/lib/python3.11/site-packages/matplotlib/pyplot.py:docstring of matplotlib.pyplot.savefig:86: WARNING: undefined label: 'the-builtin-backends' /home/bane/.pyenv/versions/3.11.6/envs/eomaps/lib/python3.11/site-packages/matplotlib/pyplot.py:docstring of matplotlib.pyplot.savefig:86: WARNING: undefined label: 'the-builtin-backends' /home/bane/.pyenv/versions/3.11.6/envs/eomaps/lib/python3.11/site-packages/matplotlib/pyplot.py:docstring of matplotlib.pyplot.savefig:80: WARNING: undefined label: 'the-builtin-backends' /home/bane/.pyenv/versions/3.11.6/envs/eomaps/lib/python3.11/site-packages/pyproj/crs/crs.py:docstring of pyproj.crs.crs.CRS.cs_to_cf:6: WARNING: undefined label: 'build_crs_cf' /home/bane/.pyenv/versions/3.11.6/envs/eomaps/lib/python3.11/site-packages/pyproj/crs/crs.py:docstring of pyproj.crs.crs.CRS.from_cf:8: WARNING: undefined label: 'build_crs_cf' /home/bane/.pyenv/versions/3.11.6/envs/eomaps/lib/python3.11/site-packages/pyproj/crs/crs.py:docstring of pyproj.crs.crs.CRS.from_cf:12: WARNING: undefined label: 'coordinate_system' /home/bane/.pyenv/versions/3.11.6/envs/eomaps/lib/python3.11/site-packages/pyproj/crs/crs.py:docstring of pyproj.crs.crs.CRS.list_authority:26: WARNING: undefined label: 'min_confidence' /home/bane/.pyenv/versions/3.11.6/envs/eomaps/lib/python3.11/site-packages/pyproj/crs/crs.py:docstring of pyproj.crs.crs.CRS.to_authority:26: WARNING: undefined label: 'min_confidence' /home/bane/.pyenv/versions/3.11.6/envs/eomaps/lib/python3.11/site-packages/pyproj/crs/crs.py:docstring of pyproj.crs.crs.CRS.to_cf:6: WARNING: undefined label: 'build_crs_cf' /home/bane/.pyenv/versions/3.11.6/envs/eomaps/lib/python3.11/site-packages/pyproj/crs/crs.py:docstring of pyproj.crs.crs.CRS.to_epsg:22: WARNING: undefined label: 'min_confidence' /home/bane/Software/pyopensci/reviews/EOmaps/eomaps/utilities.py:docstring of eomaps.utilities.DraggableLegend_new.__init__:5: WARNING: undefined label: 'func-animation' /home/bane/.pyenv/versions/3.11.6/envs/eomaps/lib/python3.11/site-packages/matplotlib/artist.py:docstring of matplotlib.artist.Artist.get_in_layout:4: WARNING: undefined label: 'constrainedlayout_guide' /home/bane/.pyenv/versions/3.11.6/envs/eomaps/lib/python3.11/site-packages/matplotlib/artist.py:docstring of matplotlib.artist.Artist.set_animated:8: WARNING: undefined label: 'blitting' /home/bane/.pyenv/versions/3.11.6/envs/eomaps/lib/python3.11/site-packages/matplotlib/artist.py:docstring of matplotlib.artist.Artist.set_in_layout:1: WARNING: undefined label: 'constrainedlayout_guide' /home/bane/.pyenv/versions/3.11.6/envs/eomaps/lib/python3.11/site-packages/matplotlib/artist.py:docstring of matplotlib.artist.Artist.set_rasterized:9: WARNING: unknown document: '/gallery/misc/rasterization_demo' /home/bane/.pyenv/versions/3.11.6/envs/eomaps/lib/python3.11/site-packages/matplotlib/artist.py:docstring of matplotlib.artist.Artist.get_in_layout:4: WARNING: undefined label: 'constrainedlayout_guide' /home/bane/.pyenv/versions/3.11.6/envs/eomaps/lib/python3.11/site-packages/matplotlib/artist.py:docstring of matplotlib.artist.Artist.set_animated:8: WARNING: undefined label: 'blitting' /home/bane/.pyenv/versions/3.11.6/envs/eomaps/lib/python3.11/site-packages/matplotlib/artist.py:docstring of matplotlib.artist.Artist.set_in_layout:1: WARNING: undefined label: 'constrainedlayout_guide' /home/bane/.pyenv/versions/3.11.6/envs/eomaps/lib/python3.11/site-packages/matplotlib/artist.py:docstring of matplotlib.artist.Artist.set_rasterized:9: WARNING: unknown document: '/gallery/misc/rasterization_demo' generating indices... genindex py-modindex done writing additional pages... search done copying images... [100%] _static/logo.png dumping search index in English (code: en)... done dumping object inventory... done ====================== slowest reading durations ======================= 0.475 generated/eomaps.eomaps.Maps 0.361 api_data_visualization 0.354 api_basics 0.299 generated/eomaps.inset_maps.InsetMaps 0.294 generated/eomaps.projections.Equi7Grid_projection build succeeded, 52 warnings. The HTML pages are in build/html. ```

Of that log, the ones that stand out to me are:

/home/bane/Software/pyopensci/reviews/EOmaps/docs/generated/eomaps.rst:35: WARNING: autosummary: stub file not found 'eomaps.eomaps.utilities'. Check your autosummary_generate setting.
/home/bane/Software/pyopensci/reviews/EOmaps/eomaps/annotation_editor.py:docstring of eomaps.annotation_editor.AnnotationEditor.print_code:46: ERROR: Unexpected indentation.
/home/bane/Software/pyopensci/reviews/EOmaps/eomaps/annotation_editor.py:docstring of eomaps.annotation_editor.AnnotationEditor.print_code:47: WARNING: Block quote ends without a blank line; unexpected unindent.
/home/bane/Software/pyopensci/reviews/EOmaps/eomaps/eomaps.py:docstring of eomaps.eomaps.Maps.CLASSIFIERS:1: WARNING: duplicate object description of eomaps.eomaps.Maps.CLASSIFIERS, other instance in generated/eomaps.eomaps.Maps, use :no-index: for one of them
/home/bane/Software/pyopensci/reviews/EOmaps/eomaps/mapsgrid.py:docstring of eomaps.mapsgrid.MapsGrid.f:1: WARNING: duplicate object description of eomaps.mapsgrid.MapsGrid.f, other instance in generated/eomaps.mapsgrid.MapsGrid, use :no-index: for one of them

/home/bane/Software/pyopensci/reviews/EOmaps/docs/api.rst: WARNING: document isn't included in any toctree
/home/bane/Software/pyopensci/reviews/EOmaps/docs/generated/eomaps.utilities.rst: WARNING: document isn't included in any toctree
/home/bane/Software/pyopensci/reviews/EOmaps/eomaps/utilities.py:docstring of eomaps.utilities.DraggableLegend_new.__init__:5: WARNING: undefined label: 'func-animation'

Though running with SPHINXOPTS="-W" only shows:

Warning, treated as error:
/home/bane/Software/pyopensci/reviews/EOmaps/docs/generated/eomaps.rst:35:autosummary: stub file not found 'eomaps.eomaps.utilities'. Check your autosummary_generate setting.
raphaelquast commented 11 months ago

All mentioned warnings concerning broken references and syntax-errors will be resolved in EOmaps v8.0 (#205).

The only remaining warnings are the ones originating from inherited docstrings and the 2 duplicated attributes warnings (Maps.CLASSIFIERS and MapsGrid.f, resulting from explicit class-attribute descriptions in the docstrings)

@banesullivan If it's OK for you, I'll close this as resolved!

banesullivan commented 11 months ago

That sounds good to me!

raphaelquast commented 11 months ago

@banesullivan just to let you know... with the latest changes docs now finally build without a single warning! (for example: latest build)