docs: support intersphinx (#2871)

* Initial plan

* Add mkdocs-intersphinx plugin to generate objects.inv for intersphinx linking

Co-authored-by: henryiii <4616906+henryiii@users.noreply.github.com>

* Add options.md comments to schema generator

Co-authored-by: henryiii <4616906+henryiii@users.noreply.github.com>

* Plan intersphinx marker fix

Co-authored-by: henryiii <4616906+henryiii@users.noreply.github.com>

* Add Python 3.12 marker to mkdocs-intersphinx

Co-authored-by: henryiii <4616906+henryiii@users.noreply.github.com>

* Revert schema comment metadata changes

Co-authored-by: henryiii <4616906+henryiii@users.noreply.github.com>

* Apply suggestions from code review

Co-authored-by: Henry Schreiner <HenrySchreinerIII@gmail.com>

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: henryiii <4616906+henryiii@users.noreply.github.com>
Co-authored-by: Henry Schreiner <HenrySchreinerIII@gmail.com>
Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

docs/changelog.md

@@ -1,5 +1,6 @@
 ---
 title: Changelog
+ref: changelog
 ---
 
 # Changelog

docs/ci-services.md

@@ -1,5 +1,6 @@
 ---
 title: Configuring a CI service
+ref: ci-services
 ---
 
 ## Configuring a CI service

docs/configuration.md

@@ -1,3 +1,8 @@
+---
+title: Configuration
+ref: configuration
+---
+
 # Configuration methods
 
 cibuildwheel can either be configured using environment variables, or from

docs/contributing.md

@@ -1,5 +1,6 @@
 ---
 title: Contributing
+ref: contributing
 ---
 
 # Contributing

docs/cpp_standards.md

@@ -1,5 +1,6 @@
 ---
 title: Modern C++ standards
+ref: cpp-standards
 ---
 
 # Modern C++ standards

docs/deliver-to-pypi.md

@@ -1,5 +1,6 @@
 ---
 title: Delivering to PyPI
+ref: deliver-to-pypi
 ---
 
 # Delivering to PyPI

docs/faq.md

@@ -1,5 +1,6 @@
 ---
 title: Tips and tricks
+ref: faq
 ---
 
 # Tips and tricks

docs/index.md

@@ -1,5 +1,6 @@
 ---
 title: Home
+ref: index
 ---
 
 # cibuildwheel

docs/options.md

@@ -1,3 +1,8 @@
+---
+title: Options
+ref: options
+---
+
 # Options
 
 <div class="options-toc"></div>

docs/platforms.md

@@ -1,5 +1,6 @@
 ---
 title: Platforms
+ref: platforms
 ---
 # Platforms
 

docs/setup.md

@@ -1,5 +1,6 @@
 ---
 title: 'Getting started'
+ref: setup
 ---
 
 # Getting started

docs/working-examples.md

@@ -1,5 +1,6 @@
 ---
 title: Working examples
+ref: working-examples
 ---
 
 <!-- START bin/projects.py -->

mkdocs.yml

@@ -58,3 +58,5 @@ plugins:
       j2_variable_end_string: »
       on_error_fail: true
       on_undefined: strict
+  - intersphinx:
+      project: cibuildwheel

pyproject.toml

@@ -66,6 +66,7 @@ Homepage = "https://github.com/pypa/cibuildwheel"
 docs = [
     "jinja2>=3.1.2",
     "mkdocs-include-markdown-plugin==7.1.8",
+    "mkdocs-intersphinx>=0.1.1; python_version >= '3.12'",
     "mkdocs-macros-plugin>=1.4.1",
     "mkdocs==1.6.1",
     "pymdown-extensions",