diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index b13277f..b55cda7 100644 --- a/.pre-commit-config.yaml +++ b/.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 diff --git a/docs/api/data.md b/docs/api/data.md index 2637569..87b7d25 100644 --- a/docs/api/data.md +++ b/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. diff --git a/docs/api/graph.md b/docs/api/graph.md index 8b2bfe0..137e353 100644 --- a/docs/api/graph.md +++ b/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. diff --git a/docs/api/metapath.md b/docs/api/metapath.md index a310dd9..57b6f8f 100644 --- a/docs/api/metapath.md +++ b/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. diff --git a/docs/api/mobility.md b/docs/api/mobility.md index 3a13dd9..d07a97c 100644 --- a/docs/api/mobility.md +++ b/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. diff --git a/docs/api/morphology.md b/docs/api/morphology.md index 6ac5ddb..c9857a3 100644 --- a/docs/api/morphology.md +++ b/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. diff --git a/docs/api/proximity.md b/docs/api/proximity.md index 3619b44..555ed0e 100644 --- a/docs/api/proximity.md +++ b/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. diff --git a/docs/api/transportation.md b/docs/api/transportation.md index 5ba87cd..8cff02d 100644 --- a/docs/api/transportation.md +++ b/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. diff --git a/docs/api/utils.md b/docs/api/utils.md index 6b8fc21..5d8b403 100644 --- a/docs/api/utils.md +++ b/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. diff --git a/docs/contributing.md b/docs/contributing.md index 8e0a628..36910a3 100644 --- a/docs/contributing.md +++ b/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 --- diff --git a/docs/installation.md b/docs/installation.md index d91d883..9e0fe66 100644 --- a/docs/installation.md +++ b/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 --- diff --git a/docs/javascripts/readthedocs.js b/docs/javascripts/readthedocs.js new file mode 100644 index 0000000..1990eb2 --- /dev/null +++ b/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 = ` +
+ + + +
`; + + // 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); + } +}); diff --git a/docs/overrides/main.html b/docs/overrides/main.html new file mode 100644 index 0000000..04e5a75 --- /dev/null +++ b/docs/overrides/main.html @@ -0,0 +1,46 @@ +{% extends "base.html" %} + +{% block site_meta %} +{{ super() }} + + +{# 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 #} + + + + + + + + + + +{# Twitter Card meta tags #} + + + + + +{# Additional SEO meta tags #} + +{% if page and page.meta and page.meta.keywords %} + +{% endif %} +{% endblock %} diff --git a/mkdocs.yml b/mkdocs.yml index 8ea208a..d3feafc 100644 --- a/mkdocs.yml +++ b/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: