Render schema in docs; update schema; update changelog

Author: brynpickering

CHANGELOG.md

@@ -23,13 +23,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Changed
 
+- Configuration validation to use a JSON schema. Partially **backward-incompatible** since configuration errors now raise exceptions rather than logging a message to the `error` level [#56](https://github.com/arup-group/osmox/pull/56).
 - Recommended installation instructions changed from using `pip` to creating a `mamba` environment [#38](https://github.com/arup-group/osmox/pull/38).
 - Supported and tested Python versions updated to py3.10 - py3.12 [#38](https://github.com/arup-group/osmox/pull/38).
 - Majority of documentation moved from README to dedicated documentation site: https://arup-group.github.io/osmox [#40](https://github.com/arup-group/osmox/pull/40).
 - Default output format changed from `.geojson` to `.gpkg` & support for multiple file formats (`.gpkg`, `.geojson`, `.parquet`) [#41](https://github.com/arup-group/osmox/issues/41)
 
 ### Added
 
+- Rendered JSON schema in documentation [#56](https://github.com/arup-group/osmox/pull/56).
 - Activity infilling can use a geospatial point data source to fill OSM `landuse` areas, e.g. postcode data points.
 - Activity infilling can take place in target areas that have existing facilities, using the `max_existing_acts_fraction` argument to set the area that existing facilities can already take up in the target geometry while still allowing infilling.
 

configs/config_UK.json

@@ -1,4 +1,5 @@
 {
+	"$schema": "../src/osmox/schema.json",
 	"filter": {
 		"building": [
 			"apartments",

configs/config_UKfill.json

@@ -1,4 +1,5 @@
 {
+	"$schema": "../src/osmox/schema.json",
 	"filter": {
 		"building": [
 			"apartments",

configs/config_UKno_transit.json

@@ -1,4 +1,5 @@
 {
+    "$schema": "../src/osmox/schema.json",
     "filter": {
         "building": [
             "apartments",
@@ -34,7 +35,7 @@
             "sports_hall",
             "stadium",
             "yes"
-        ]        
+        ]
     },
 
     "object_features": ["units", "levels", "area", "floor_area"],

configs/example.json

@@ -1,4 +1,5 @@
 {
+    "$schema": "../src/osmox/schema.json",
     "filter": {
         "building": [
             "apartments",

docs/config.md

@@ -9,6 +9,10 @@ osmox validate <CONFIG PATH>
 
 OSMOX features and associated configurations are described in the sections below.
 
+!!! info "See also"
+    We use a configuration schema to validate the configuration files you input - malformed files will cause OSMOX to fail fast and early.
+    You can read a detailed description of the configuration as described in the schema [here](schema.md).
+
 !!! warning
     These configs get very long - see the full examples in the `configs` to get an idea.
 

docs/static/hooks.py

@@ -1,8 +1,10 @@
 import tempfile
 from pathlib import Path
 
+import jsonschema2md
 import mkdocs.plugins
 from mkdocs.structure.files import File
+from osmox.config import SCHEMA
 
 TEMPDIR = tempfile.TemporaryDirectory()
 # Add to this list if you want to ignore any other source files from the documentation API reference
@@ -16,7 +18,7 @@ def on_files(files: list, config: dict, **kwargs):
     for file in Path("./resources").glob("**/*.*"):
         files.append(_new_file(file, config))
     files.append(_new_file(Path("./CHANGELOG.md"), config))
-
+    files.append(_schema_to_md(SCHEMA, config))
     api_nav = _api_gen(files, config)
     _update_nav(api_nav, config)
 
@@ -137,6 +139,34 @@ def _get_nav_list(nav: list[dict | str], ref: str) -> list:
     return nav_ref[ref]
 
 
+def _schema_to_md(schema: dict, config: dict) -> File:
+    """Parse a JSON schema to Markdown, edit some lines, then dump to file
+
+    Args:
+        schema (dict): Path to the YAML schema to be converted.
+    """
+    output_file = "schema.md"
+    output_full_filepath = Path(TEMPDIR.name) / output_file
+    output_full_filepath.parent.mkdir(exist_ok=True, parents=True)
+
+    parser = jsonschema2md.Parser()
+    parser.tab_size = 4
+
+    lines = parser.parse_schema(schema)
+
+    assert lines[2] == "## Properties\n\n"
+    del lines[2]
+
+    output_full_filepath.write_text("\n".join(lines))
+
+    return File(
+        path=output_file,
+        src_dir=TEMPDIR.name,
+        dest_dir=config["site_dir"],
+        use_directory_urls=config["use_directory_urls"],
+    )
+
+
 @mkdocs.plugins.event_priority(-100)
 def on_post_build(**kwargs):
     """After mkdocs has finished building the docs, remove the temporary directory of markdown files.

mkdocs.yml

@@ -5,6 +5,7 @@ nav:
   - quick_start.md
   - osmox_run.md
   - config.md
+  - Configuration schema: schema.md
   - Contributing: contributing.md
   - Changelog: CHANGELOG.md
   - Reference:

pyproject.toml

@@ -68,7 +68,7 @@ where = ["src"]
 # Add file globs from the source code directory if they include non-py files that should be packaged
 # E.g. "fixtures/**/*"
 # "py.typed" is added by default. It allows `mypy` to register the package as having type hints.
-osmox = ["py.typed"]
+osmox = ["py.typed", "schema.json"]
 
 
 [build-system]

requirements/base.txt

@@ -1,4 +1,5 @@
 click < 9
+jsonschema >= 4, < 5
 geopandas >= 0.13, < 0.15
 osmium < 3.7
 pandas >= 1.5, < 3

requirements/dev.txt

@@ -1,4 +1,5 @@
 cruft >= 2, < 3
+jsonschema2md >= 1.1, < 2
 mike >= 2, < 3
 mkdocs < 2
 mkdocs-material >= 9.4, < 10