Update docs for mkdocs & readthedocs optimization

.pre-commit-config.yaml

@@ -10,6 +10,7 @@ repos:
       - id: check-shebang-scripts-are-executable
       - id: check-toml
       - id: check-yaml
+        exclude: ^mkdocs\.yml$  # MkDocs uses custom !ENV tags
       - id: detect-private-key
       - id: end-of-file-fixer
       - id: fix-byte-order-marker
@@ -22,6 +23,7 @@ repos:
     hooks:
       - id: yamllint
         args: [--strict, --config-file=./tests/.yamllint.yml]
+        exclude: ^mkdocs\.yml$  # MkDocs uses custom syntax
 
   - repo: https://github.com/numpy/numpydoc
     rev: v1.9.0

docs/api/data.md

@@ -1,3 +1,8 @@
+---
+description: API reference for the Data module. Load and process geospatial data from Overture Maps, including buildings, roads, places, and administrative boundaries for graph construction.
+keywords: Overture Maps, load_overture_data, buildings, roads, places, segments, geospatial data, OpenStreetMap alternative, urban data
+---
+
 # Data Module
 
 The data module provides functions for loading and processing geospatial data from various sources, with a focus on [Overture Maps](https://overturemaps.org/) data.

docs/api/graph.md

@@ -1,3 +1,8 @@
+---
+description: API reference for the Graph module. Convert between GeoDataFrames, NetworkX graphs, and PyTorch Geometric (PyG) data objects for geospatial deep learning workflows.
+keywords: PyTorch Geometric, GeoDataFrame, NetworkX, graph conversion, HeteroData, Data, gdf_to_pyg, pyg_to_gdf, geospatial deep learning, graph neural networks
+---
+
 # Graph Module
 
 The graph module provides functions for converting between different graph representations, including GeoDataFrames, NetworkX graphs, and PyTorch Geometric data objects.

docs/api/metapath.md

@@ -1,3 +1,8 @@
+---
+description: API reference for the Metapath module. Add metapath-derived edges to heterogeneous graphs for graph neural network architectures like HAN and HGT.
+keywords: metapath, heterogeneous graph, HAN, HGT, add_metapaths, graph neural networks, edge aggregation, multi-relational graphs, HGNN
+---
+
 # Metapath Module
 
 The metapath module provides functions for adding metapath-derived edges to heterogeneous graphs.

docs/api/mobility.md

@@ -1,3 +1,8 @@
+---
+description: API reference for the Mobility module. Convert Origin-Destination (OD) matrices into graph representations for modelling human mobility flows, migration, and commuting patterns.
+keywords: OD matrix, origin-destination, mobility flows, migration, commuting, human mobility, od_matrix_to_graph, flow networks, spatial interaction
+---
+
 # Mobility Module
 
 The mobility module provides functions for processing Origin-Destination (OD) matrices and creating mobility networks for urban flow analysis.

docs/api/morphology.md

@@ -1,3 +1,8 @@
+---
+description: API reference for the Morphology module. Create morphological graphs from urban form data capturing relationships between buildings, streets, tessellations, and public spaces.
+keywords: urban morphology, morphological graph, buildings, streets, tessellation, dual graph, momepy, urban form analysis, spatial structure
+---
+
 # Morphology Module
 
 The morphology module provides functions for creating morphological graphs from urban form data, capturing spatial relationships between buildings, streets, and public spaces.

docs/api/proximity.md

@@ -1,3 +1,8 @@
+---
+description: API reference for the Proximity module. Generate spatial graphs using KNN, Delaunay, Gabriel, Waxman algorithms, contiguity relations, and node bridging for POI and zone analysis.
+keywords: KNN graph, Delaunay triangulation, Gabriel graph, Waxman graph, contiguity, spatial proximity, bridge_nodes, group_nodes, POI analysis, spatial networks
+---
+
 # Proximity Module
 
 The proximity module provides functions for generating proximity-based graph networks from spatial data. These algorithms create edges between geometries based on various spatial relationships.

docs/api/transportation.md

@@ -1,3 +1,8 @@
+---
+description: API reference for the Transportation module. Process GTFS schedules and create public transit network graphs for accessibility analysis and multi-modal routing.
+keywords: GTFS, public transport, transit network, bus, train, tram, accessibility analysis, travel summary, multi-modal routing, load_gtfs
+---
+
 # Transportation Module
 
 The transportation module provides functions for processing GTFS (General Transit Feed Specification) data and creating transportation network graphs.

docs/api/utils.md

@@ -1,3 +1,8 @@
+---
+description: API reference for the Utils module. Utility functions for graph conversion between GeoDataFrame, NetworkX and rustworkx, validation, tessellation, isochrone creation, and plotting.
+keywords: gdf_to_nx, nx_to_gdf, rustworkx, tessellation, isochrone, dual_graph, plot_graph, graph validation, spatial utilities
+---
+
 # Utils Module
 
 The utils module provides core utility functions for graph conversion, validation, and visualization.

docs/contributing.md

@@ -1,5 +1,6 @@
 ---
 description: Guidelines for contributing to City2Graph. Learn how to report bugs, suggest features, and submit pull requests to help improve the project.
+keywords: contributing, pull request, bug report, feature request, development environment, pre-commit, pytest, code style, ruff, documentation
 hide:
   - navigation
 ---

docs/installation.md

@@ -1,5 +1,6 @@
 ---
 description: Step-by-step guide to installing City2Graph via pip or conda, including instructions for PyTorch Geometric and CUDA support for GPU acceleration.
+keywords: install city2graph, pip install, conda install, PyTorch Geometric, CUDA, GPU acceleration, Python package, conda-forge, cu118, cu124, cu126, cu128, cu130
 hide:
   - navigation
 ---

docs/javascripts/readthedocs.js

@@ -0,0 +1,47 @@
+// ReadTheDocs integration for MkDocs Material
+
+// Trigger Read the Docs' search addon instead of Material MkDocs default
+document.addEventListener("DOMContentLoaded", function(event) {
+    const searchInput = document.querySelector(".md-search__input");
+    if (searchInput) {
+        searchInput.addEventListener("focus", (e) => {
+            const event = new CustomEvent("readthedocs-search-show");
+            document.dispatchEvent(event);
+        });
+    }
+});
+
+// Use CustomEvent to generate the version selector
+document.addEventListener(
+    "readthedocs-addons-data-ready",
+    function (event) {
+        const config = event.detail.data();
+        const versioning = `
+<div class="md-version">
+<button class="md-version__current" aria-label="Select version">
+    ${config.versions.current.slug}
+</button>
+
+<ul class="md-version__list">
+${ config.versions.active.map(
+    (version) => `
+    <li class="md-version__item">
+    <a href="${ version.urls.documentation }" class="md-version__link">
+        ${ version.slug }
+    </a>
+            </li>`).join("\n")}
+</ul>
+</div>`;
+
+    // Check if we already added versions and remove them if so.
+    // This happens when using the "Instant loading" feature.
+    // See https://squidfunk.github.io/mkdocs-material/setup/setting-up-navigation/#instant-loading
+    const currentVersions = document.querySelector(".md-version");
+    if (currentVersions !== null) {
+      currentVersions.remove();
+    }
+    const headerTopic = document.querySelector(".md-header__topic");
+    if (headerTopic) {
+        headerTopic.insertAdjacentHTML("beforeend", versioning);
+    }
+});

docs/overrides/main.html

@@ -0,0 +1,46 @@
+{% extends "base.html" %}
+
+{% block site_meta %}
+{{ super() }}
+<meta name="readthedocs-addons-api-version" content="1" />
+
+{# Custom Social Card Meta Tags for SEO #}
+{% set social_image = config.site_url ~ "assets/logos/social_preview_city2graph.png" %}
+
+{# Use page-specific description if available, otherwise use site description #}
+{% if page and page.meta and page.meta.description %}
+  {% set page_description = page.meta.description %}
+{% else %}
+  {% set page_description = config.site_description %}
+{% endif %}
+
+{# Build page title #}
+{% if page and page.title %}
+  {% set page_title = page.title ~ " - " ~ config.site_name %}
+{% else %}
+  {% set page_title = config.site_name %}
+{% endif %}
+
+{# Open Graph meta tags #}
+<meta property="og:type" content="website" />
+<meta property="og:site_name" content="{{ config.site_name }}" />
+<meta property="og:title" content="{{ page_title }}" />
+<meta property="og:description" content="{{ page_description }}" />
+<meta property="og:image" content="{{ social_image }}" />
+<meta property="og:image:type" content="image/png" />
+<meta property="og:image:width" content="1280" />
+<meta property="og:image:height" content="640" />
+<meta property="og:url" content="{{ page.canonical_url }}" />
+
+{# Twitter Card meta tags #}
+<meta name="twitter:card" content="summary_large_image" />
+<meta name="twitter:title" content="{{ page_title }}" />
+<meta name="twitter:description" content="{{ page_description }}" />
+<meta name="twitter:image" content="{{ social_image }}" />
+
+{# Additional SEO meta tags #}
+<meta name="author" content="{{ config.site_author }}" />
+{% if page and page.meta and page.meta.keywords %}
+<meta name="keywords" content="{{ page.meta.keywords }}" />
+{% endif %}
+{% endblock %}

mkdocs.yml

@@ -1,5 +1,5 @@
 site_name: City2Graph
-site_url: https://city2graph.net/latest/
+site_url: !ENV [READTHEDOCS_CANONICAL_URL, 'https://city2graph.net/latest/']
 site_author: Yuta Sato
 site_description: >-
   City2Graph is a Python library to transform geospatial data (OSM, GTFS, POIs)
@@ -60,12 +60,14 @@ extra_javascript:
   - https://unpkg.com/mathjax@3/es5/tex-mml-chtml.js
   - javascripts/gtag.js
   - javascripts/redirect.js
+  - javascripts/readthedocs.js
 
 # Plugins
 plugins:
   - search
   - mike
-  - social
+  # social plugin disabled - using custom OG meta tags in overrides/main.html instead
+  # (social plugin requires Cairo which may not be available on all systems)
   - git-revision-date-localized:
       enable_creation_date: true
   - minify: