Register the routing table label before parallel reading

CHANGELOG.rst

@@ -18,6 +18,8 @@ Major changes
 Minor changes
 .............
 
+-   Fixed references to the HTTP routing table on clean parallel builds. [:issue:`58`]
+
 
 Version 2.2.1
 `````````````

src/sphinxcontrib/httpdomain/__init__.py

@@ -800,17 +800,19 @@ def content_callback(self, match):
     }
 
 
-def register_routingtable_as_label(app, document):
-    labels = app.env.domaindata['std']['labels']
+def register_routingtable_as_label(app, env, docnames):
+    # Register in the main environment: parallel readers only merge labels
+    # belonging to source documents, not generated index pages.
+    labels = env.domaindata['std']['labels']
     labels['routingtable'] = 'http-routingtable', '', _('HTTP Routing Table')
-    anonlabels = app.env.domaindata['std']['anonlabels']
+    anonlabels = env.domaindata['std']['anonlabels']
     anonlabels['routingtable'] = 'http-routingtable', ''
 
 
 def setup(app):
     app.add_domain(HTTPDomain)
     app.add_domain(WebSocketDomain)
-    app.connect('doctree-read', register_routingtable_as_label)
+    app.connect('env-before-read-docs', register_routingtable_as_label)
 
     package_dir = os.path.abspath(os.path.dirname(__file__))
     locale_dir = os.path.join(package_dir, 'locale')

tests/routingtable_test.py

@@ -0,0 +1,46 @@
+import pytest
+
+from websocket_test import build, inventory_uri, load_inventory, write_project
+
+
+@pytest.mark.parametrize('jobs', [1, 2])
+def test_routingtable_reference_on_clean_and_incremental_build(tmp_path, jobs):
+    sources = {
+        'index.rst': '''
+            API
+            ===
+
+            .. toctree::
+
+               routes
+               references
+        ''',
+        'routes.rst': '''
+            Routes
+            ======
+
+            .. http:get:: /health
+        ''',
+        'references.rst': '''
+            References
+            ==========
+
+            :ref:`routingtable`
+
+            :ref:`All routes <routingtable>`
+        ''',
+    }
+    source = write_project(tmp_path, sources)
+    for stage in ('clean', 'incremental', 'unchanged'):
+        if stage == 'incremental':
+            with (source / 'references.rst').open('a', encoding='utf-8') as page:
+                page.write('\nUpdated reference: :ref:`routingtable`\n')
+        result, output = build(source, tmp_path, jobs=jobs)
+        assert result.returncode == 0, result.stdout + result.stderr
+        page = (output / 'references.html').read_text(encoding='utf-8')
+        assert 'href="http-routingtable.html"' in page
+        assert 'HTTP Routing Table' in page
+        assert 'All routes' in page
+        assert (output / 'http-routingtable.html').exists()
+        inventory = load_inventory(output)
+        assert inventory_uri(inventory['std:label']['routingtable']) == 'http-routingtable.html'