hawkmoth.ext.transformations and hawkmoth.util.doccompat deprecation

CHANGELOG.rst

@@ -10,6 +10,24 @@ Changed
 ~~~~~~~
 
 * Bumped Python dependency requirement to v3.9, as v3.8 is reaching end of life
+* 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.
+
+Removed
+~~~~~~~
+
+* ``hawkmoth --compat={none,javadoc-basic,javadoc-liberal,kernel-doc}`` option
+  from CLI
+* ``cautodoc_root`` configuration option in favour of ``hawkmoth_root``
+* ``cautodoc_clang`` configuration option in favour of ``hawkmoth_clang``
 
 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
 

doc/extension.rst

@@ -105,24 +105,3 @@ See also additional configuration options in the :ref:`built-in extensions
    .. code-block:: python
 
       hawkmoth_source_uri = 'https://example.org/src/{source}#L{line}'
-
-.. py:data:: cautodoc_root
-   :type: str
-
-   Equivalent to :py:data:`hawkmoth_root`.
-
-   .. warning::
-
-      The ``cautodoc_root`` option has been deprecated in favour of the
-      :py:data:`hawkmoth_root` option and will be removed in the future.
-
-.. py:data:: cautodoc_clang
-   :type: str
-
-   Equivalent to :py:data:`hawkmoth_clang`.
-
-   .. warning::
-
-      The ``cautodoc_clang`` option has been deprecated in favour of
-      the :py:data:`hawkmoth_clang` option and will be removed in the
-      future.

src/hawkmoth/__init__.py

@@ -348,31 +348,11 @@ def _doctree_read(app, doctree):
             onlynode += nodes.reference('', '', inline, internal=False, refuri=uri)
             signode += onlynode
 
-def _deprecate(conf, old, new, default=None):
-    if conf[old]:
-        logger = logging.getLogger(__name__)
-        logger.warning(f'{old} is deprecated in favour of {new}')
-        conf[new] = conf[old]
-        del conf[old]
-        return conf[new]
-    return default
-
 def setup(app):
     app.require_sphinx('3.0')
 
-    app.add_config_value('cautodoc_root', None, 'env', [str])
-    app.add_config_value('cautodoc_clang', None, 'env', [list])
-
-    app.add_config_value(
-        'hawkmoth_root',
-        lambda conf: _deprecate(conf, 'cautodoc_root', 'hawkmoth_root', app.confdir),
-        'env', [str]
-    )
-    app.add_config_value(
-        'hawkmoth_clang',
-        lambda conf: _deprecate(conf, 'cautodoc_clang', 'hawkmoth_clang', []),
-        'env', [list]
-    )
+    app.add_config_value('hawkmoth_root', app.confdir, 'env', [str])
+    app.add_config_value('hawkmoth_clang', [], 'env', [list])
 
     app.add_config_value('hawkmoth_transform_default', None, 'env', [str])
 
@@ -399,9 +379,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/__main__.py

@@ -14,7 +14,6 @@
 from hawkmoth.ext import javadoc
 from hawkmoth.ext import napoleon
 from hawkmoth.parser import parse
-from hawkmoth.util import doccompat
 
 def filename(file):
     if os.path.isfile(file):
@@ -31,11 +30,6 @@ def _process_docstring(transform, lines):
     if fn:
         fn(lines)
 
-def _process_docstring_compat(args, lines):
-    text = '\n'.join(lines)
-    text = doccompat.convert(text, transform=args.compat)
-    lines[:] = [line for line in text.splitlines()]
-
 def _read_version():
     try:
         with open(os.path.join(os.path.abspath(os.path.dirname(__file__)),
@@ -64,16 +58,8 @@ def main():
                             'napoleon',
                         ],
                         help='Process docstring.')
-    compat.add_argument('--compat',
-                        choices=[
-                            'none',
-                            'javadoc-basic',
-                            'javadoc-liberal',
-                            'kernel-doc'
-                        ],
-                        help='Compatibility options. See cautodoc_compat.')
     parser.add_argument('--clang', metavar='PARAM', action='append',
-                        help='Argument to pass to Clang. May be specified multiple times. See cautodoc_clang.')  # noqa: E501
+                        help='Argument to pass to Clang. May be specified multiple times. See hawkmoth_clang.')  # noqa: E501
     parser.add_argument('--verbose', dest='verbose', action='store_true',
                         help='Verbose output.')
     parser.add_argument('--version', action='version',
@@ -86,7 +72,7 @@ def main():
     if args.process_docstring:
         def process_docstring(lines): return _process_docstring(args.process_docstring, lines)
     else:
-        def process_docstring(lines): return _process_docstring_compat(args, lines)
+        process_docstring = None
 
     for comment in comments.walk():
         if args.verbose:

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
 #