chore: sync with microG unofficial installer

Signed-off-by: ale5000 <15793015+ale5000-git@users.noreply.github.com>

Author: ale5000-git

.readthedocs.yaml

@@ -14,7 +14,7 @@ build:
     python: "3"
   jobs:
     post_install:
-      - pip install sphinx-rtd-theme
+      - pip install Sphinx==9.1.0 sphinx-rtd-theme
 
 # Build documentation in the "docs/" directory with Sphinx
 sphinx:

docs/INSTRUCTIONS.rst

@@ -35,6 +35,8 @@ The following custom recoveries are supported:
 - `Omni Recovery <https://github.com/omnirom/android_bootable_recovery>`_
 
 
+.. _download:
+
 Download
 ========
 

docs/conf.py

@@ -7,9 +7,12 @@
 # For the full list of built-in configuration values, see the documentation: https://www.sphinx-doc.org/en/master/usage/configuration.html
 
 import os
-import re
 import subprocess
+
 from docutils import nodes
+from sphinx import addnodes
+from sphinx.util import logging
+
 
 def get_version():
     props_path = os.path.join(os.path.dirname(__file__), '..', 'zip-content', 'module.prop')
@@ -21,6 +24,7 @@ def get_version():
                     return line.replace('version=', '').lstrip('v').strip()
     return '0.0.0-unknown'
 
+
 def get_revision():
     # Try Read the Docs env vars first
     git_rev = os.environ.get('READTHEDOCS_GIT_COMMIT_HASH')
@@ -37,23 +41,52 @@ def get_revision():
     except Exception:
         return None
 
-def transform_doc_links(app, docname, source):
-    """Phase 1: Convert local .rst links (no anchor) to :doc: roles."""
-    source[0] = re.sub(r'`([^`<]+)\s*<((?!http|mailto)[^>]+)\.rst>`_', r':doc:`\1 <\2>`', source[0])
 
-def fix_anchors_in_tree(app, doctree, docname):
-    """Phase 2: Fix local .rst#anchor links in the resolved tree."""
-    ext = '.pdf' if app.builder.name == 'latex' else '.html'
-    for node in doctree.traverse(nodes.reference):
-        uri = node.get('refuri')
-        if uri and '.rst#' in uri and not uri.startswith(('http', 'mailto')):
-            node['refuri'] = uri.replace('.rst#', f'{ext}#')
+def transform_rst_links(app, doctree):
+    """
+    Automatically converts internal .rst file links to Sphinx cross-references
+    (:doc: or :ref:), enabling validation and proper path resolution.
+    """
+
+    docname = app.env.docname
+    # Traverse only reference nodes that have a 'refuri' attribute
+    for node in doctree.findall(nodes.reference):
+        uri = node.get('refuri', '')
+        if '.rst' not in uri or uri.startswith(('http', 'mailto:', '//')):
+            continue
+
+        parts = uri.split('#', 1)
+        has_anchor = len(parts) > 1
+        reftype = 'ref' if has_anchor else 'doc'
+        reftarget = parts[1] if has_anchor else parts[0].removesuffix('.rst')
+        logger.info(f"[DEBUG] Converting {uri} -> :{reftype}:`{reftarget}`")
+
+        # Create pending_xref node which Sphinx resolves during build phase
+        new_node = addnodes.pending_xref(
+            '',
+            reftype=reftype,
+            refdomain='std',
+            reftarget=reftarget,
+            refdoc=docname,
+            refwarn=True,
+            refexplicit=True
+        )
+        # Transfer children (the link text) and replace the original node
+        new_node.extend(node.children)
+        node.replace_self(new_node)
+
 
 def setup(app):
-    # Process text before parsing
-    app.connect('source-read', transform_doc_links)
-    # Process nodes after tree is built
-    app.connect('doctree-resolved', fix_anchors_in_tree)
+    # Hook to modify the document structure before rendering
+    app.connect('doctree-read', transform_rst_links)
+    return {
+        'version': '0.1',
+        'parallel_read_safe': True,
+        'parallel_write_safe': True
+    }
+
+
+logger = logging.getLogger(__name__)
 
 # Project information
 project = 'Google sync add-on'
@@ -95,3 +128,11 @@ def setup(app):
     'github_version': 'main',
     'conf_py_path': '/docs/'
 }
+
+# Options for LaTeX output (e.g., PDF)
+if 'latex_elements' not in locals():
+    latex_elements = {}
+
+# The 'openany' option allows chapters to begin on the next available page;
+# this prevents unwanted blank pages by allowing starts on even or odd pages
+latex_elements['extraclassoptions'] = (latex_elements.get('extraclassoptions', '') + ',openany').strip(',')