docs: use sphinx-syntax over sphinx-a4doc

Author: clonker

docs/_static/css/custom-dark.css

@@ -590,6 +590,6 @@
   stroke: white;
 }
 
-:root[style*=dark] .a4 .sig-name {
+:root[style*=dark] .sig-name {
   background-color: transparent !important;
 }

docs/conf.py

@@ -92,13 +92,15 @@ def get_github_username_repo(url):
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
-    'sphinx_a4doc',
+    'sphinx_syntax',
     'html_extra_template_renderer',
     'remix_code_links',
     'sphinx.ext.imgconverter',
 ]
 
-a4_base_path = os.path.dirname(__file__) + '/grammar'
+syntax_base_path = 'grammar'
+# generate link anchors compatible with Sphinx-A4Doc’s naming
+syntax_a4doc_compat_links = True
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
@@ -182,7 +184,8 @@ def get_github_username_repo(url):
 # documentation.
 html_theme_options = {
     'logo_only': True,
-    'display_version': True,
+    'version_selector': True,
+    'language_selector': True,
 }
 
 # Add any paths that contain custom themes here, relative to this directory.

docs/grammar.rst

@@ -2,12 +2,12 @@
 Language Grammar
 ****************
 
-.. a4:autogrammar:: SolidityParser
-   :only-reachable-from: SolidityParser.sourceUnit
+.. syntax:autogrammar:: SolidityParser.g4
+   :root-rule: SolidityParser.sourceUnit
    :undocumented:
    :cc-to-dash:
 
-.. a4:autogrammar:: SolidityLexer
-   :only-reachable-from: SolidityParser.sourceUnit
+.. syntax:autogrammar:: SolidityLexer.g4
+   :root-rule: SolidityParser.sourceUnit
    :fragments:
    :cc-to-dash:

docs/requirements.txt

@@ -2,12 +2,11 @@
 # which could result in it being installed anyway and the style (especially bullet points) being broken.
 # See https://github.com/readthedocs/sphinx_rtd_theme/issues/1115
 # theme >=3.0.0 removes the display_version option in favor of version_selector and language_selector
-sphinx_rtd_theme>=0.5.2, <3.0.0
+# Use rtd theme version that supports sphinx>=8.0
+sphinx_rtd_theme>=3.0.0
 
 pygments-lexer-solidity>=0.7.0
-sphinx-a4doc>=1.6.0; python_version < '3.13'
-# todo remove this once there is a version > 1.6.0
-sphinx-a4doc @ git+https://github.com/taminomara/sphinx-a4doc@f63d3b2; python_version >= '3.13'
+sphinx-syntax>=1.0.1
 
-# Sphinx 2.1.0 is the oldest version that accepts a lexer class in add_lexer()
-sphinx>=2.1.0, <9.0
+# Sphinx version constraints for sphinx-syntax compatibility
+sphinx>=8.0.0, <9.0.0