From fb0502e55c3e9dc02980cc688173e2ee1e1eee00 Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 6 Nov 2026 19:33:06 +0000 Subject: [PATCH 1/2] docs(api): fix reStructuredText in module docstrings and read_db_conf Sphinx reported "Unexpected indentation" on six module docstrings whose continuation lines were indented, and an unfinished emphasis on the unescaped *.dbconf of read_db_conf. Use a reStructuredText field list for the Name/Purpose/Author headers, dedent the others and put the glob in a literal. AI-Level: 7 AI-Model: Claude Sonnet 5.5 Co-Authored-By: Claude Sonnet 5.5 Claude-Session: https://claude.ai/code/session_01CUNZAXTg3vthj5KZYCgf3m --- dicogis/georeaders/read_vector_flat_dataset.py | 11 +++++------ dicogis/ui/main.py | 4 ++-- dicogis/ui/mw_dicogis.py | 4 ++-- dicogis/ui/wdg_tab_publish.py | 9 ++++----- dicogis/ui/workers.py | 9 ++++----- dicogis/utils/db_conf_reader.py | 2 +- dicogis/utils/progress.py | 9 ++++----- 7 files changed, 22 insertions(+), 26 deletions(-) diff --git a/dicogis/georeaders/read_vector_flat_dataset.py b/dicogis/georeaders/read_vector_flat_dataset.py index d715c925..2ea75220 100644 --- a/dicogis/georeaders/read_vector_flat_dataset.py +++ b/dicogis/georeaders/read_vector_flat_dataset.py @@ -1,12 +1,11 @@ #! python3 # noqa: E265 """ -Name: InfosSHP -Purpose: Use GDAL/OGR library to extract informations about - geographic data. It permits a more friendly use as - submodule. - -Author: Julien Moura (https://github.com/Guts/) +:Name: InfosSHP +:Purpose: Use GDAL/OGR library to extract informations about + geographic data. It permits a more friendly use as + submodule. +:Author: Julien Moura (https://github.com/Guts/) """ # ############################################################################ diff --git a/dicogis/ui/main.py b/dicogis/ui/main.py index 2484e84a..4b23590d 100644 --- a/dicogis/ui/main.py +++ b/dicogis/ui/main.py @@ -4,8 +4,8 @@ """ DicoGIS Automatize the creation of a dictionnary of geographic data - contained in a folders structures. - It produces an Excel output file (.xlsx) +contained in a folders structures. +It produces an Excel output file (.xlsx) Julien Moura (@geojulien) """ diff --git a/dicogis/ui/mw_dicogis.py b/dicogis/ui/mw_dicogis.py index 7b91ce99..fe142e17 100644 --- a/dicogis/ui/mw_dicogis.py +++ b/dicogis/ui/mw_dicogis.py @@ -4,8 +4,8 @@ """ DicoGIS Automatize the creation of a dictionnary of geographic data - contained in a folders structures. - It produces an Excel output file (.xlsx) +contained in a folders structures. +It produces an Excel output file (.xlsx) Julien Moura (@geojulien) """ diff --git a/dicogis/ui/wdg_tab_publish.py b/dicogis/ui/wdg_tab_publish.py index f674c12b..d6fe469b 100644 --- a/dicogis/ui/wdg_tab_publish.py +++ b/dicogis/ui/wdg_tab_publish.py @@ -2,11 +2,10 @@ """ -Name: TabPublish -Purpose: Tab to publish previously exported metadata (JSON files) to a - uData catalog, from DicoGIS Notebook. - -Author: Julien Moura (@geojulien) +:Name: TabPublish +:Purpose: Tab to publish previously exported metadata (JSON files) to a + uData catalog, from DicoGIS Notebook. +:Author: Julien Moura (@geojulien) """ # ############################################################################## diff --git a/dicogis/ui/workers.py b/dicogis/ui/workers.py index 0a2058e9..19af09fc 100644 --- a/dicogis/ui/workers.py +++ b/dicogis/ui/workers.py @@ -2,11 +2,10 @@ """ -Name: Workers -Purpose: QThread-based workers running long tasks off the GUI thread, plus a - Qt-signal-based implementation of the ProgressReporter protocol. - -Author: Julien Moura (@geojulien) +:Name: Workers +:Purpose: QThread-based workers running long tasks off the GUI thread, plus a + Qt-signal-based implementation of the ProgressReporter protocol. +:Author: Julien Moura (@geojulien) """ # ############################################################################## diff --git a/dicogis/utils/db_conf_reader.py b/dicogis/utils/db_conf_reader.py index e833d1d2..4cd26399 100644 --- a/dicogis/utils/db_conf_reader.py +++ b/dicogis/utils/db_conf_reader.py @@ -28,7 +28,7 @@ def read_db_conf(dbconf_path: Path) -> list | dict: """Read databases configuration files and return parameters as list of dictionaries. Args: - dbconf_path (Path): filepath to *.dbconf file + dbconf_path (Path): filepath to ``*.dbconf`` file Raises: TypeError: if input filepath is not an instance of pathlib.Path diff --git a/dicogis/utils/progress.py b/dicogis/utils/progress.py index fd4a66bd..eaec3822 100644 --- a/dicogis/utils/progress.py +++ b/dicogis/utils/progress.py @@ -2,11 +2,10 @@ """ -Name: Progress -Purpose: Toolkit-agnostic contract used by the processing pipeline to - report progress and to be told to stop. - -Author: Julien Moura (@geojulien) +:Name: Progress +:Purpose: Toolkit-agnostic contract used by the processing pipeline to + report progress and to be told to stop. +:Author: Julien Moura (@geojulien) """ # ############################################################################## From ce29ed67742fe829cf5dae3aac3bf09c7c2c2f64 Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 6 Nov 2026 19:33:06 +0000 Subject: [PATCH 2/2] docs(api): drop the generic PyQt docstring of signals Autodoc documents every pyqtSignal with PyQt's own docstring, whose "*types" docutils reads as an unfinished emphasis, producing a warning per signal. Remove it from the processed docstring, leaving the signals documented by a docstring of their own untouched. AI-Level: 7 AI-Model: Claude Sonnet 5.5 Co-Authored-By: Claude Sonnet 5.5 Claude-Session: https://claude.ai/code/session_01CUNZAXTg3vthj5KZYCgf3m --- docs/conf.py | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/docs/conf.py b/docs/conf.py index a8dcf962..fd119d92 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -217,6 +217,16 @@ def run_apidoc(_): main(["-e", "-f", "-M", "-o", str(output_path), str(modules)] + exclusions) +def drop_pyqt_signal_docstring(app, what, name, obj, options, lines): + """Remove the generic docstring PyQt gives to signals without their own. + + It contains `*types`, which docutils reads as an unfinished emphasis. + """ + if lines and lines[0].endswith("-> PYQT_SIGNAL"): + lines.clear() + + # launch setup def setup(app): app.connect("builder-inited", run_apidoc) + app.connect("autodoc-process-docstring", drop_pyqt_signal_docstring)