docs: render Google-style docstrings and document datetime scale classes

The documentation build reported 3 errors and 1 warning: the docstrings
of the qwt.qtdesigner module follow the Google style (Args/Returns), which
Sphinx does not understand without the napoleon extension. Besides,
QwtDateTimeScaleDraw and QwtDateTimeScaleEngine were missing from the
reference documentation.

- doc/conf.py: enable sphinx.ext.napoleon.
- Add QwtDateTimeScaleDraw and QwtDateTimeScaleEngine to the module
  documentation of qwt.scale_draw and qwt.scale_engine.
- QwtDateTimeScaleDraw.get_format/label: drop the return types from the
  Returns sections (already in the signatures), as "QwtText" was an
  ambiguous cross-reference.
- QwtPlotLayout.expandLineBreaks: move its "Returns:" list into the
  `:return:` field, which napoleon would otherwise misinterpret.
- Changelog entry.

`sphinx -b html doc ... -W` now succeeds without any warning. Compared
with a build without napoleon, only the qtdesigner, scale and plot_layout
reference pages change.

Refs #115

Assisted-by: Claude Opus 5.5

Author: PierreRaybaut

CHANGELOG.md

@@ -24,6 +24,7 @@
 ### Other changes
 
 - The source distribution now includes the Qt Designer plugin (`qtdesigner/qwtplugin.py`, see the "Qt Designer" section of the documentation) and this changelog ([Issue #115](https://github.com/PlotPyStack/PythonQwt/issues/115))
+- Documentation: the reference of the `qwt.qtdesigner` module, whose docstrings follow the Google style, is now rendered properly (it produced formatting errors), and `QwtDateTimeScaleDraw` and `QwtDateTimeScaleEngine` are now documented ([Issue #115](https://github.com/PlotPyStack/PythonQwt/issues/115))
 
 ## Version 0.16.3
 

doc/conf.py

@@ -19,7 +19,7 @@
 
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = ["sphinx.ext.autodoc"]
+extensions = ["sphinx.ext.autodoc", "sphinx.ext.napoleon"]
 try:
     import sphinx.ext.viewcode  # noqa: F401
 

qwt/plot_layout.py

@@ -746,9 +746,7 @@ def expandLineBreaks(self, options, rect):
 
         :param options: Options how to layout the legend
         :param QRectF rect: Bounding rectangle for title, footer, axes and canvas.
-        :return: tuple `(dimTitle, dimFooter, dimAxes)`
-
-        Returns:
+        :return: tuple `(dimTitle, dimFooter, dimAxes)`, where:
 
             * `dimTitle`: Expanded height of the title widget
             * `dimFooter`: Expanded height of the footer widget

qwt/scale_draw.py

@@ -17,6 +17,12 @@
 
 .. autoclass:: QwtScaleDraw
    :members:
+
+QwtDateTimeScaleDraw
+--------------------
+
+.. autoclass:: QwtDateTimeScaleDraw
+   :members:
 """
 
 import math
@@ -1294,7 +1300,7 @@ def get_format(self) -> str:
         """Get the current datetime format string
 
         Returns:
-            str: Format string
+            Format string
         """
         return self._format
 
@@ -1313,7 +1319,7 @@ def label(self, value: float) -> QwtText:
             value: Unix timestamp (seconds since epoch)
 
         Returns:
-            QwtText: Formatted label
+            Formatted label
         """
         try:
             dt = datetime.fromtimestamp(value)

qwt/scale_engine.py

@@ -23,6 +23,12 @@
 
 .. autoclass:: QwtLogScaleEngine
    :members:
+
+QwtDateTimeScaleEngine
+----------------------
+
+.. autoclass:: QwtDateTimeScaleEngine
+   :members:
 """
 
 import math