search

Open-EO / openeo-python-client

Python client API for OpenEO
https://open-eo.github.io/openeo-python-client/
Apache License 2.0
156 stars 42 forks source link

resolve warnings in doc build #503

Closed soxofaan closed 4 months ago

soxofaan commented 1 year ago

I noticed quite a lot of warnings in when building docs locally today:

.../openeo/rest/datacube.py:docstring of openeo.rest.datacube.DataCube.add:3: WARNING: Explicit markup ends without a blank line; unexpected unindent.
.../openeo/rest/datacube.py:docstring of openeo.rest.datacube.DataCube.filter_bands:5: WARNING: Explicit markup ends without a blank line; unexpected unindent.
.../openeo/rest/datacube.py:docstring of openeo.rest.datacube.DataCube.load_collection:5: WARNING: Explicit markup ends without a blank line; unexpected unindent.
.../openeo/rest/datacube.py:docstring of openeo.rest.datacube.DataCube.divide:3: WARNING: Explicit markup ends without a blank line; unexpected unindent.
.../openeo/rest/datacube.py:docstring of openeo.rest.datacube.DataCube.process:5: WARNING: Explicit markup ends without a blank line; unexpected unindent.
.../openeo/rest/datacube.py:docstring of openeo.rest.datacube.DataCube.ln:3: WARNING: Explicit markup ends without a blank line; unexpected unindent.
.../openeo/rest/datacube.py:docstring of openeo.rest.datacube.DataCube.log10:3: WARNING: Explicit markup ends without a blank line; unexpected unindent.
.../openeo/rest/datacube.py:docstring of openeo.rest.datacube.DataCube.log2:3: WARNING: Explicit markup ends without a blank line; unexpected unindent.
.../openeo/rest/datacube.py:docstring of openeo.rest.datacube.DataCube.logarithm:3: WARNING: Explicit markup ends without a blank line; unexpected unindent.
.../openeo/rest/datacube.py:docstring of openeo.rest.datacube.DataCube.merge_cubes:5: WARNING: Explicit markup ends without a blank line; unexpected unindent.
.../openeo/rest/datacube.py:docstring of openeo.rest.datacube.DataCube.multiply:3: WARNING: Explicit markup ends without a blank line; unexpected unindent.
.../openeo/rest/datacube.py:docstring of openeo.rest.datacube.DataCube.normalized_difference:3: WARNING: Explicit markup ends without a blank line; unexpected unindent.
.../openeo/rest/datacube.py:docstring of openeo.rest.datacube.DataCube.reduce_temporal:5: WARNING: Explicit markup ends without a blank line; unexpected unindent.
.../openeo/rest/datacube.py:docstring of openeo.rest.datacube.DataCube.resample_spatial:3: WARNING: Explicit markup ends without a blank line; unexpected unindent.
.../openeo/rest/datacube.py:docstring of openeo.rest.datacube.DataCube.save_result:3: WARNING: Explicit markup ends without a blank line; unexpected unindent.
.../openeo/rest/datacube.py:docstring of openeo.rest.datacube.DataCube.create_job:5: WARNING: Explicit markup ends without a blank line; unexpected unindent.
.../openeo/rest/datacube.py:docstring of openeo.rest.datacube.DataCube.subtract:3: WARNING: Explicit markup ends without a blank line; unexpected unindent.
.../openeo/rest/vectorcube.py:docstring of openeo.rest.vectorcube.VectorCube.filter_bands:6: WARNING: Explicit markup ends without a blank line; unexpected unindent.
.../openeo/rest/vectorcube.py:docstring of openeo.rest.vectorcube.VectorCube.filter_bbox:6: WARNING: Explicit markup ends without a blank line; unexpected unindent.
.../openeo/rest/vectorcube.py:docstring of openeo.rest.vectorcube.VectorCube.filter_labels:6: WARNING: Explicit markup ends without a blank line; unexpected unindent.
.../openeo/rest/vectorcube.py:docstring of openeo.rest.vectorcube.VectorCube.filter_vector:6: WARNING: Explicit markup ends without a blank line; unexpected unindent.
.../openeo/rest/vectorcube.py:docstring of openeo.rest.vectorcube.VectorCube.create_job:5: WARNING: Explicit markup ends without a blank line; unexpected unindent.
.../openeo/rest/connection.py:docstring of openeo.rest.connection.Connection.load_collection:5: WARNING: Explicit markup ends without a blank line; unexpected unindent.
.../openeo/rest/connection.py:docstring of openeo.rest.connection.Connection.list_output_formats:5: WARNING: Explicit markup ends without a blank line; unexpected unindent.
.../openeo/rest/connection.py:docstring of openeo.rest.connection.Connection.user_jobs:4: WARNING: Explicit markup ends without a blank line; unexpected unindent.
.../openeo/rest/conversions.py:docstring of openeo.rest.conversions.datacube_from_file:4: WARNING: Explicit markup ends without a blank line; unexpected unindent.
.../openeo/processes.py:docstring of openeo.processes:1: WARNING: duplicate object description of openeo.processes, other instance in api-processes, use :no-index: for one of them
.../openeo/processes.py:docstring of openeo.processes:1: WARNING: duplicate object description of openeo.processes, other instance in api, use :no-index: for one of them
.../openeo/processes.py:docstring of openeo.processes:1: WARNING: duplicate object description of openeo.processes, other instance in api-processes, use :no-index: for one of them
.../docs/configuration.rst:90: WARNING: Definition list ends without a blank line; unexpected unindent.
.../docs/cookbook/localprocessing.rst:3: WARNING: Duplicate explicit target name: "here".
.../docs/cookbook/localprocessing.rst:3: WARNING: Duplicate explicit target name: "here".
.../docs/development.rst:5: WARNING: Duplicate explicit target name: "pypi".
.../docs/basics.rst:141: WARNING: undefined label: 'temporal-extent-handling'

Might be good to give this a look.

also to consider: fail the doc build if there are (too much) warnings?

soxofaan commented 4 months ago

I could zone in on these "WARNING: Explicit markup ends without a blank line; unexpected unindent." warnings: https://github.com/tox-dev/sphinx-autodoc-typehints/issues/467

soxofaan commented 4 months ago

majority of "WARNING: Explicit markup ends without a blank line; unexpected unindent" is actually from the legacy_alias helper which uses [deprecated[(https://pypi.org/project/Deprecated/) to append a deprecation note in the docs, but sphinx_autodoc_typehints directly appends a line after that which is bad reStructuredtext style

soxofaan commented 4 months ago

https://github.com/tox-dev/sphinx-autodoc-typehints/issues/467 is already resolved and they released version 2.2.3 which includes the fix :partying_face: eliminating a bunch of doc build warnings