extensions: deprecate hawkmoth.ext.transformations and hawkmoth.util.…

…doccompat

The introduction of the cautodoc_transformations config option was a
mistake to begin with. The right way forward is the
hawkmoth-process-docstring event. The hawkmoth.ext.transformations
extension was introduced as a temporary solution to not immediately pull
the plug on cautodoc_transformations.

It's time to deprecate the cautodoc_transformations config, the
hawkmoth.ext.transformations extension, and the hawkmoth.util.doccompat
module.

Everyone should move to either the hawkmoth.ext.javadoc or
hawkmoth.ext.napoleon extensions, or if they're not enough, implement
their own extensions through the hawkmoth-process-docstring event. The
javadoc/doxygen helpers in doccompat are inferior to the
hawkmoth.ext.javadoc extension, and the kernel-doc "support" is two
regexes in a row.

Functionally, the deprecation means 1) not loading
hawkmoth.ext.transformations automatically, i.e. you have to manually
add it to extensions in conf.py, and 2) deprecation messages on loading
the extension and the module.

CHANGELOG.rst

@@ -6,6 +6,20 @@ Unreleased `master`_
 
 :Date: YYYY-MM-DD
 
+Changed
+~~~~~~~
+
+* The ``hawkmoth.ext.transformations`` extension is no longer loaded
+  automatically as it has been deprecated
+
+Deprecated
+~~~~~~~~~~
+
+* The ``hawkmoth.ext.transformations`` extension and the
+  ``hawkmoth.util.doccompat`` module in favour of the ``hawkmoth.ext.javadoc``
+  and ``hawkmoth.ext.napoleon`` extensions and the
+  ``hawkmoth-process-docstring`` event.
+
 Hawkmoth `0.18.0`_
 ------------------
 

doc/built-in-extensions.rst

@@ -130,14 +130,12 @@ hawkmoth.ext.transformations
 This extension handles the :py:data:`cautodoc_transformations` feature, using
 the :event:`hawkmoth-process-docstring` event.
 
-.. note::
+.. warning::
 
-   Going forward, it's recommended to handle transformations using the event
-   directly instead of :py:data:`cautodoc_transformations`. This built-in
-   extension provides backward compatibility for the functionality.
-
-   For now, this extension is loaded by default, and the installation step below
-   is not strictly necessary. This will change in the future.
+   The ``hawkmoth.ext.transformations`` extension has been deprecated, and will
+   be removed in the future. Please use either the :ref:`hawkmoth.ext.javadoc`
+   or :ref:`hawkmoth.ext.napoleon` extensions, or, for more flexibility, the
+   :event:`hawkmoth-process-docstring` event directly.
 
 Installation and configuration in ``conf.py``:
 
@@ -184,3 +182,8 @@ Installation and configuration in ``conf.py``:
           'javadoc-liberal': doccompat.javadoc_liberal,
           'kernel-doc': doccompat.kerneldoc,
       }
+
+   .. warning::
+
+      The ``hawkmoth.util.doccompat`` package has been deprecated, and will be
+      removed in the future.

doc/directives.rst

@@ -30,8 +30,6 @@ included.
       Override :data:`hawkmoth_transform_default` for the ``transform``
       parameter value of the :event:`hawkmoth-process-docstring` event.
 
-      See also :ref:`hawkmoth.ext.transformations`.
-
    .. rst:directive:option:: clang
       :type: text
 

src/hawkmoth/__init__.py

@@ -399,9 +399,6 @@ def setup(app):
 
     app.add_event('hawkmoth-process-docstring')
 
-    # Setup transformations for compatibility.
-    app.setup_extension('hawkmoth.ext.transformations')
-
     # Source code link
     app.add_config_value('hawkmoth_source_uri', None, 'env', [str])
     app.connect('doctree-read', _doctree_read)

src/hawkmoth/ext/transformations/__init__.py

@@ -1,6 +1,8 @@
 # Copyright (c) 2023, Jani Nikula <[email protected]>
 # Licensed under the terms of BSD 2-Clause, see LICENSE for details.
 
+from sphinx.util import logging
+
 def _process_docstring(app, lines, transform, options):
     transformations = app.config.cautodoc_transformations
     tropt = options.get('transform')
@@ -22,6 +24,9 @@ def _process_docstring(app, lines, transform, options):
     lines[:] = comment.splitlines()[:]
 
 def setup(app):
+    logger = logging.getLogger(__name__)
+    logger.warning('hawkmoth.ext.transformations extension has been deprecated.')
+
     app.add_config_value('cautodoc_transformations', None, 'env', [dict])
 
     # Run before event handlers with default priority.

src/hawkmoth/util/doccompat.py

@@ -9,6 +9,10 @@
 """
 
 import re
+from sphinx.util import logging
+
+logger = logging.getLogger(__name__)
+logger.warning('hawkmoth.util.doccompat module has been deprecated.')
 
 # Basic Javadoc/Doxygen/kernel-doc import
 #