I'm inclined to keep the replaced_by_pep8 decorator, as it gives a good place to emit a DeprecationWarning when I do the 3.1.0 release.

That makes sense. What would you think about still referencing the individual modules directly for Sphinx? It would make it more straightforward to include documentation for module-level variables like alphanums, empty, common_html_entity, or ParseAction.

The alternative, if we wanted to document any variables, would be to put their documentation directly in __init__.py, separate from the actual definition. Either of the following options would keep mypy happy:

common_html_entity: ParserElement = common_html_entity
"""Convenience parser for common HTML entities"""

common_html_entity: ParserElement  # type: ignore[no-redef]
"""Convenience parser for common HTML entities"""

Looking at this, but late now - will pick up some time tomorrow.

Please don't remove the replaced_by_pep8 decorators. As I said, I'm going to use those to emit DeprecationWarnings starting in pyparsing 3.1.0