docs(api): fix the Sphinx warnings of module docstrings and PyQt signals

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/)
 """
 
 # ############################################################################

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)
 """

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)
 """

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)
 """
 
 # ##############################################################################

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)
 """
 
 # ##############################################################################

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

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)
 """
 
 # ##############################################################################

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)