From 783b81d0e115f2943e97a17d22d1da0d595ca381 Mon Sep 17 00:00:00 2001
From: Duncan Dewhurst <duncan.dewhurst@opendataservices.coop>
Date: Tue, 11 Jun 2024 15:50:31 +0100
Subject: [PATCH 1/4] network-schema: Add version placeholders

---
 schema/network-schema.json | 50 +++++++++++++++++++-------------------
 1 file changed, 25 insertions(+), 25 deletions(-)

diff --git a/schema/network-schema.json b/schema/network-schema.json
index 9ee1eb9..f3b62ad 100644
--- a/schema/network-schema.json
+++ b/schema/network-schema.json
@@ -11,7 +11,7 @@
   "properties": {
     "id": {
       "title": "Identifier",
-      "description": "A universally unique identifier for this network, as defined by [RFC 4122](https://datatracker.ietf.org/doc/html/rfc4122). For more information, see the [identifier reference](https://open-fibre-data-standard.readthedocs.io/en/latest/reference/identifiers.html).",
+      "description": "A universally unique identifier for this network, as defined by [RFC 4122](https://datatracker.ietf.org/doc/html/rfc4122). For more information, see the [identifier reference](https://open-fibre-data-standard.readthedocs.io/en/{{version}}/reference/identifiers.html).",
       "format": "uuid",
       "type": "string"
     },
@@ -23,7 +23,7 @@
     },
     "nodes": {
       "title": "Nodes",
-      "description": "Information about the nodes that belong to this network. Information about nodes should be embedded in this field unless:\n\n* The network is too large to load in to memory, in which case a link to a streamable bulk nodes file may be provided in `.links`\n* The data is published via an API and the network is too large to return in a single API response, in which case a link to a paginated nodes endpoint may be provided in `.links`.\n\nFor more information, see [how to format data for publication](https://open-fibre-data-standard.readthedocs.io/en/latest/guidance/publication.html#how-to-format-data-for-publication).",
+      "description": "Information about the nodes that belong to this network. Information about nodes should be embedded in this field unless:\n\n* The network is too large to load in to memory, in which case a link to a streamable bulk nodes file may be provided in `.links`\n* The data is published via an API and the network is too large to return in a single API response, in which case a link to a paginated nodes endpoint may be provided in `.links`.\n\nFor more information, see [how to format data for publication](https://open-fibre-data-standard.readthedocs.io/en/{{version}}/guidance/publication.html#how-to-format-data-for-publication).",
       "type": "array",
       "items": {
         "$ref": "#/$defs/Node"
@@ -33,7 +33,7 @@
     },
     "spans": {
       "title": "Spans",
-      "description": "Information about the spans that belong to this network. Information about spans should be embedded in this field unless:\n\n* The network is too large to load in to memory, in which case a link to a streamable bulk spans file may be provided in `.links`\n* The data is published via an API and the network is too large to return in a single API response, in which case a link to a paginated spans endpoint may be provided in `.links`.\n\nFor more information, see [how to format data for publication](https://open-fibre-data-standard.readthedocs.io/en/latest/guidance/publication.html#how-to-format-data-for-publication).",
+      "description": "Information about the spans that belong to this network. Information about spans should be embedded in this field unless:\n\n* The network is too large to load in to memory, in which case a link to a streamable bulk spans file may be provided in `.links`\n* The data is published via an API and the network is too large to return in a single API response, in which case a link to a paginated spans endpoint may be provided in `.links`.\n\nFor more information, see [how to format data for publication](https://open-fibre-data-standard.readthedocs.io/en/{{version}}/guidance/publication.html#how-to-format-data-for-publication).",
       "type": "array",
       "items": {
         "$ref": "#/$defs/Span"
@@ -129,7 +129,7 @@
     },
     "language": {
       "title": "Language",
-      "description": "The default language of this network,from the open [language codelist](https://open-fibre-data-standard.readthedocs.io/en/latest/reference/codelists.html#language). A [BCP47 language tag](https://www.w3.org/International/articles/language-tags/) is allowed, if there is a user need for the additional information.",
+      "description": "The default language of this network,from the open [language codelist](https://open-fibre-data-standard.readthedocs.io/en/{{version}}/reference/codelists.html#language). A [BCP47 language tag](https://www.w3.org/International/articles/language-tags/) is allowed, if there is a user need for the additional information.",
       "type": "string",
       "codelist": "language.csv",
       "openCodelist": true,
@@ -137,7 +137,7 @@
     },
     "links": {
       "title": "Links",
-      "description": "Links to related resources. The first item in the links array must be a link to the canonical JSON schema that describes the structure of the data. Links to API endpoints for nodes and spans should be provided when a network is too large to return in a single API response and links to bulk files should be provided when a network is too large to load into memory, for more information, see [how to publish large networks](https://open-fibre-data-standard.readthedocs.io/en/latest/guidance/publication.html#how-to-publish-large-networks).",
+      "description": "Links to related resources. The first item in the links array must be a link to the canonical JSON schema that describes the structure of the data. Links to API endpoints for nodes and spans should be provided when a network is too large to return in a single API response and links to bulk files should be provided when a network is too large to load into memory, for more information, see [how to publish large networks](https://open-fibre-data-standard.readthedocs.io/en/{{version}}/guidance/publication.html#how-to-publish-large-networks).",
       "type": "array",
       "prefixItems": [
         {
@@ -186,7 +186,7 @@
         },
         "status": {
           "title": "Status",
-          "description": "The status of this node, from the closed [nodeStatus codelist](https://open-fibre-data-standard.readthedocs.io/en/latest/reference/codelists.html#nodestatus).",
+          "description": "The status of this node, from the closed [nodeStatus codelist](https://open-fibre-data-standard.readthedocs.io/en/{{version}}/reference/codelists.html#nodestatus).",
           "type": "string",
           "codelist": "nodeStatus.csv",
           "openCodelist": false,
@@ -201,7 +201,7 @@
         },
         "location": {
           "title": "Node location",
-          "description": "In the [JSON publication format](https://open-fibre-data-standard.readthedocs.io/en/latest/reference/publication_formats/json.html), a GeoJSON [Point](https://datatracker.ietf.org/doc/html/rfc7946#section-3.1.4) geometry describing the physical location of this node. In the [CSV publication format](https://open-fibre-data-standard.readthedocs.io/en/latest/reference/publication_formats/csv.html), a [well-known text](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry) POINT geometry.",
+          "description": "In the [JSON publication format](https://open-fibre-data-standard.readthedocs.io/en/{{version}}/reference/publication_formats/json.html), a GeoJSON [Point](https://datatracker.ietf.org/doc/html/rfc7946#section-3.1.4) geometry describing the physical location of this node. In the [CSV publication format](https://open-fibre-data-standard.readthedocs.io/en/{{version}}/reference/publication_formats/csv.html), a [well-known text](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry) POINT geometry.",
           "$ref": "#/$defs/Geometry"
         },
         "address": {
@@ -211,7 +211,7 @@
         },
         "type": {
           "title": "Node type",
-          "description": "The type of this node, from the open [nodeType codelist](https://open-fibre-data-standard.readthedocs.io/en/latest/reference/codelists.html#nodetype). For nodes with multiple network providers, the union of the node types for each provider.",
+          "description": "The type of this node, from the open [nodeType codelist](https://open-fibre-data-standard.readthedocs.io/en/{{version}}/reference/codelists.html#nodetype). For nodes with multiple network providers, the union of the node types for each provider.",
           "type": "array",
           "items": {
             "type": [
@@ -247,7 +247,7 @@
         },
         "technologies": {
           "title": "Technologies",
-          "description": "The active technologies used at this node, from the open [nodeTechnologies codelist](https://open-fibre-data-standard.readthedocs.io/en/latest/reference/codelists.html#nodetechnologies). For nodes with multiple network providers, the union of the active technologies used by each provider.",
+          "description": "The active technologies used at this node, from the open [nodeTechnologies codelist](https://open-fibre-data-standard.readthedocs.io/en/{{version}}/reference/codelists.html#nodetechnologies). For nodes with multiple network providers, the union of the active technologies used by each provider.",
           "type": "array",
           "items": {
             "type": [
@@ -306,7 +306,7 @@
         },
         "status": {
           "title": "Span status",
-          "description": "The status of the network infrastructure for this span, from the closed [spanStatus codelist](https://open-fibre-data-standard.readthedocs.io/en/latest/reference/codelists.html#spanstatus).",
+          "description": "The status of the network infrastructure for this span, from the closed [spanStatus codelist](https://open-fibre-data-standard.readthedocs.io/en/{{version}}/reference/codelists.html#spanstatus).",
           "type": "string",
           "codelist": "spanStatus.csv",
           "openCodelist": false,
@@ -346,7 +346,7 @@
         },
         "route": {
           "title": "Span route",
-          "description": "In the [JSON publication format](https://open-fibre-data-standard.readthedocs.io/en/latest/reference/publication_formats/json.html), a GeoJSON [LineString](https://datatracker.ietf.org/doc/html/rfc7946#section-3.1.4) geometry describing the route of this span. In the [CSV publication format](https://open-fibre-data-standard.readthedocs.io/en/latest/reference/publication_formats/csv.html), a [well-known text](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry) LINESTRING geometry.",
+          "description": "In the [JSON publication format](https://open-fibre-data-standard.readthedocs.io/en/{{version}}/reference/publication_formats/json.html), a GeoJSON [LineString](https://datatracker.ietf.org/doc/html/rfc7946#section-3.1.4) geometry describing the route of this span. In the [CSV publication format](https://open-fibre-data-standard.readthedocs.io/en/{{version}}/reference/publication_formats/csv.html), a [well-known text](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry) LINESTRING geometry.",
           "$ref": "#/$defs/Geometry"
         },
         "physicalInfrastructureProvider": {
@@ -372,7 +372,7 @@
         },
         "transmissionMedium": {
           "title": "Transmission medium",
-          "description": "The physical media of this span, from the closed [transmissionMedium codelist](https://open-fibre-data-standard.readthedocs.io/en/latest/reference/codelists.html#transmissionmedium).",
+          "description": "The physical media of this span, from the closed [transmissionMedium codelist](https://open-fibre-data-standard.readthedocs.io/en/{{version}}/reference/codelists.html#transmissionmedium).",
           "type": "array",
           "items": {
             "type": [
@@ -393,7 +393,7 @@
         },
         "deployment": {
           "title": "Deployment",
-          "description": "The physical deployment of this span, from the closed [deployment codelist](https://open-fibre-data-standard.readthedocs.io/en/latest/reference/codelists.html#deployment). Further details of this span's deployment can be provided in `.deploymentDetails`.",
+          "description": "The physical deployment of this span, from the closed [deployment codelist](https://open-fibre-data-standard.readthedocs.io/en/{{version}}/reference/codelists.html#deployment). Further details of this span's deployment can be provided in `.deploymentDetails`.",
           "type": "array",
           "items": {
             "type": [
@@ -423,7 +423,7 @@
         },
         "fibreType": {
           "title": "Fibre type",
-          "description": "The type of fibre used in this span, from the closed [fibreType codelist](https://open-fibre-data-standard.readthedocs.io/en/latest/reference/codelists.html#fibretype). Further details of the span's fibre type can be provided in `.fibreTypeDetails`.",
+          "description": "The type of fibre used in this span, from the closed [fibreType codelist](https://open-fibre-data-standard.readthedocs.io/en/{{version}}/reference/codelists.html#fibretype). Further details of the span's fibre type can be provided in `.fibreTypeDetails`.",
           "type": "string",
           "codelist": "fibreType.csv",
           "openCodelist": false,
@@ -456,7 +456,7 @@
         },
         "technologies": {
           "title": "Technologies",
-          "description": "The active technologies used on this span, from the open [spanTechnologies codelist](https://open-fibre-data-standard.readthedocs.io/en/latest/reference/codelists.html#spantechnologies). For spans with multiple network providers, the union of the active technologies used by each provider.",
+          "description": "The active technologies used on this span, from the open [spanTechnologies codelist](https://open-fibre-data-standard.readthedocs.io/en/{{version}}/reference/codelists.html#spantechnologies). For spans with multiple network providers, the union of the active technologies used by each provider.",
           "type": "array",
           "items": {
             "type": [
@@ -482,7 +482,7 @@
         },
         "countries": {
           "title": "Countries",
-          "description": "The countries in which this span is physically located, from the closed [country codelist](https://open-fibre-data-standard.readthedocs.io/en/latest/reference/codelists.html#country).",
+          "description": "The countries in which this span is physically located, from the closed [country codelist](https://open-fibre-data-standard.readthedocs.io/en/{{version}}/reference/codelists.html#country).",
           "type": "array",
           "items": {
             "type": [
@@ -816,7 +816,7 @@
         },
         "country": {
           "title": "Country",
-          "description": "The country in which this organisation is legally registered, from the closed [country codelist](https://open-fibre-data-standard.readthedocs.io/en/latest/reference/codelists.html#country).",
+          "description": "The country in which this organisation is legally registered, from the closed [country codelist](https://open-fibre-data-standard.readthedocs.io/en/{{version}}/reference/codelists.html#country).",
           "type": "string",
           "codelist": "country.csv",
           "openCodelist": false,
@@ -1075,7 +1075,7 @@
         },
         "roles": {
           "title": "Roles",
-          "description": "This organisation's roles in this network, from the open [organisationRole codelist](https://open-fibre-data-standard.readthedocs.io/en/latest/reference/codelists.html#organisationrole). Further details about this organisation's roles can be provided in `.roleDetails`.",
+          "description": "This organisation's roles in this network, from the open [organisationRole codelist](https://open-fibre-data-standard.readthedocs.io/en/{{version}}/reference/codelists.html#organisationrole). Further details about this organisation's roles can be provided in `.roleDetails`.",
           "type": "array",
           "items": {
             "type": [
@@ -1139,7 +1139,7 @@
         },
         "type": {
           "title": "Contract type",
-          "description": "The type of this contract, from the open [contractType codelist](https://open-fibre-data-standard.readthedocs.io/en/latest/reference/codelists.html#contracttype).",
+          "description": "The type of this contract, from the open [contractType codelist](https://open-fibre-data-standard.readthedocs.io/en/{{version}}/reference/codelists.html#contracttype).",
           "type": "string",
           "codelist": "contractType.csv",
           "openCodelist": true,
@@ -1190,7 +1190,7 @@
       "properties": {
         "type": {
           "title": "Type",
-          "description": "The [GeoJSON geometry type](https://datatracker.ietf.org/doc/html/rfc7946#section-1.4) that is described by `.coordinates`, from the closed [geometryType codelist](https://open-fibre-data-standard.readthedocs.io/en/latest/reference/codelists.html#geometrytype). This must be 'Point' when referenced by `Node.location`, and 'LineString' when referenced by `Span.route`.",
+          "description": "The [GeoJSON geometry type](https://datatracker.ietf.org/doc/html/rfc7946#section-1.4) that is described by `.coordinates`, from the closed [geometryType codelist](https://open-fibre-data-standard.readthedocs.io/en/{{version}}/reference/codelists.html#geometrytype). This must be 'Point' when referenced by `Node.location`, and 'LineString' when referenced by `Span.route`.",
           "type": "string",
           "codelist": "geometryType.csv",
           "openCodelist": false,
@@ -1297,7 +1297,7 @@
         },
         "country": {
           "title": "Country",
-          "description": "The country in which the address is physically located, from the closed [country codelist](https://open-fibre-data-standard.readthedocs.io/en/latest/reference/codelists.html#country).",
+          "description": "The country in which the address is physically located, from the closed [country codelist](https://open-fibre-data-standard.readthedocs.io/en/{{version}}/reference/codelists.html#country).",
           "type": "string",
           "codelist": "country.csv",
           "openCodelist": false,
@@ -1570,7 +1570,7 @@
         },
         "currency": {
           "title": "Currency",
-          "description": "The currency of this value, from the closed [currency codelist](https://open-fibre-data-standard.readthedocs.io/en/latest/reference/codelists.html#currency).",
+          "description": "The currency of this value, from the closed [currency codelist](https://open-fibre-data-standard.readthedocs.io/en/{{version}}/reference/codelists.html#currency).",
           "type": "string",
           "codelist": "currency.csv",
           "openCodelist": false,
@@ -1910,7 +1910,7 @@
         },
         "format": {
           "title": "Format",
-          "description": "The format of this document, from the open [mediaType codelist](https://open-fibre-data-standard.readthedocs.io/en/latest/reference/codelists.html#mediatype).",
+          "description": "The format of this document, from the open [mediaType codelist](https://open-fibre-data-standard.readthedocs.io/en/{{version}}/reference/codelists.html#mediatype).",
           "type": "string",
           "codelist": "mediaType.csv",
           "openCodelist": true,
@@ -1932,7 +1932,7 @@
         },
         "scheme": {
           "title": "Scheme",
-          "description": "The register from which the identifier in `.id` is drawn, from the open [organisationIdentifierScheme codelist](https://open-fibre-data-standard.readthedocs.io/en/latest/reference/codelists.html#organisationidentifierscheme).",
+          "description": "The register from which the identifier in `.id` is drawn, from the open [organisationIdentifierScheme codelist](https://open-fibre-data-standard.readthedocs.io/en/{{version}}/reference/codelists.html#organisationidentifierscheme).",
           "type": "string",
           "codelist": "organisationIdentifierScheme.csv",
           "openCodelist": true,
@@ -1996,7 +1996,7 @@
         },
         "rel": {
           "title": "Link relation type",
-          "description": "The relationship with this related resource, from the open [linkRelationType codelist](https://open-fibre-data-standard.readthedocs.io/en/latest/reference/codelists.html#linkrelationtype). The 'describedby' code must only be used in the first item in the `links` array to link to the schema that describes the structure of the data.",
+          "description": "The relationship with this related resource, from the open [linkRelationType codelist](https://open-fibre-data-standard.readthedocs.io/en/{{version}}/reference/codelists.html#linkrelationtype). The 'describedby' code must only be used in the first item in the `links` array to link to the schema that describes the structure of the data.",
           "type": "string",
           "codelist": "linkRelationType.csv",
           "openCodelist": true,

From 7365a75f23506a69db15293de7801fa13c0119db Mon Sep 17 00:00:00 2001
From: Duncan Dewhurst <duncan.dewhurst@opendataservices.coop>
Date: Tue, 11 Jun 2024 15:50:50 +0100
Subject: [PATCH 2/4] Replace version placeholders in built schema

---
 .gitignore        |  1 +
 .readthedocs.yaml |  3 +-
 docs/Makefile     | 10 +++----
 docs/conf.py      | 72 +++++++++++++++++++++++++++++++++++++++++++++--
 4 files changed, 78 insertions(+), 8 deletions(-)

diff --git a/.gitignore b/.gitignore
index 52c9e2a..1bbf6a5 100644
--- a/.gitignore
+++ b/.gitignore
@@ -5,3 +5,4 @@ _build
 .python-version
 .vscode
 tests/__pycache__
+_readthedocs
diff --git a/.readthedocs.yaml b/.readthedocs.yaml
index 38c7a37..c554653 100644
--- a/.readthedocs.yaml
+++ b/.readthedocs.yaml
@@ -18,6 +18,7 @@ build:
 # Build documentation in the docs/ directory with Sphinx
 sphinx:
    configuration: docs/conf.py
+   builder: dirhtml
 
 # If using Sphinx, optionally build your docs in additional formats such as PDF
 # formats:
@@ -26,4 +27,4 @@ sphinx:
 # Optionally declare the Python requirements required to build your docs
 python:
    install:
-   - requirements: requirements.txt
\ No newline at end of file
+   - requirements: requirements.txt
diff --git a/docs/Makefile b/docs/Makefile
index 9cedfd9..7b056eb 100644
--- a/docs/Makefile
+++ b/docs/Makefile
@@ -5,7 +5,7 @@
 SPHINXOPTS    =
 SPHINXBUILD   = sphinx-build
 PAPER         =
-BUILDDIR      = _build
+BUILDDIR      = _readthedocs
 
 # Internal variables.
 PAPEROPT_a4     = -D latex_paper_size=a4
@@ -56,9 +56,9 @@ html:
 
 .PHONY: dirhtml
 dirhtml:
-	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
+	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/html
 	@echo
-	@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
 
 .PHONY: singlehtml
 singlehtml:
@@ -226,6 +226,6 @@ dummy:
 
 .PHONY: autobuild
 autobuild:
-	sphinx-autobuild -nW -q -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
+	sphinx-autobuild --re-ignore='docs/_readthedocs/*' -nW -q -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/html
 	@echo
-	@echo "Auto-build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
\ No newline at end of file
+	@echo "Auto-build finished. The HTML pages are in $(BUILDDIR)/html."
diff --git a/docs/conf.py b/docs/conf.py
index 49dc5bf..ada85e3 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -20,6 +20,9 @@
 # import os
 # import sys
 # sys.path.insert(0, os.path.abspath('.'))
+import json
+import os
+import shutil
 
 # -- General configuration ------------------------------------------------
 
@@ -98,7 +101,7 @@
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This patterns also effect to html_static_path and html_extra_path
-exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store','_static/docson']
+exclude_patterns = ['_build', '_readthedocs', 'Thumbs.db', '.DS_Store','_static/docson']
 
 # The reST default role (used for this markup: `text`) to use for all
 # documents.
@@ -369,4 +372,69 @@
 
 linkcheck_ignore = [
     'https://linux.die.net/man/3/libuuid',  # 403 Client Error: Forbidden for url
-]
\ No newline at end of file
+]
+
+# Substitute branch name placeholders in schema.
+
+def create_directory(path):
+    output_dir = os.path.dirname(path)
+    os.makedirs(output_dir, exist_ok=True)  
+
+def replace_substring_in_json(file_path, search_substring, replace_string, output_path=None):
+    # Read the JSON file
+    with open(file_path, 'r') as file:
+        data = json.load(file)
+
+    # Recursively search and replace the substring in the JSON data
+    _replace_substring_in_json(data, search_substring, replace_string)
+
+    # Set output path
+    if output_path is None:
+        output_path = file_path
+
+    # Create the directory if it does not exist
+    create_directory(output_path)
+
+    # Write the modified JSON data to the output file
+    with open(output_path, 'w') as file:
+        json.dump(data, file, indent=4)
+
+def _replace_substring_in_json(data, search_substring, replace_string):
+    if isinstance(data, dict):
+        for key, value in data.items():
+            if isinstance(value, str):
+                data[key] = value.replace(search_substring, replace_string)
+            else:
+                _replace_substring_in_json(value, search_substring, replace_string)
+    elif isinstance(data, list):
+        for i, item in enumerate(data):
+            if isinstance(item, str):
+                data[i] = item.replace(search_substring, replace_string)
+            else:
+                _replace_substring_in_json(item, search_substring, replace_string)
+
+
+def setup(app):
+    # Connect handlers to events
+    app.connect('config-inited', config_inited)
+    app.connect('env-before-read-docs', env_before_read_docs)
+    app.connect('build-finished', build_finished)
+
+
+def config_inited(app, config):
+    shutil.copytree('../schema', '../.temp', dirs_exist_ok=True)
+    
+    rtd_version = os.getenv('READTHEDOCS_VERSION')
+
+    # Replace {{version}} placeholders
+    if rtd_version is not None:
+        replace_substring_in_json('../.temp/network-schema.json', '{{version}}', rtd_version)     
+
+
+def env_before_read_docs(app, env, docnames):
+    create_directory('_readthedocs/html/')
+    shutil.copyfile('../.temp/network-schema.json', '_readthedocs/html/network-schema.json')
+
+
+def build_finished(app, exception):
+    shutil.rmtree('../.temp')

From 1fd9820e27d2c440aea72e788e90fb06051bbbd2 Mon Sep 17 00:00:00 2001
From: Duncan Dewhurst <duncan.dewhurst@opendataservices.coop>
Date: Tue, 11 Jun 2024 16:34:58 +0100
Subject: [PATCH 3/4] docs: Link to built schema

---
 docs/guidance/publication.md              |  2 +-
 docs/primer/scopeandkeyconcepts.md        |  6 +-
 docs/reference/identifiers.md             |  2 +-
 docs/reference/publication_formats/csv.md | 26 ++++----
 docs/reference/schema.md                  | 72 +++++++++++------------
 manage.py                                 |  6 +-
 6 files changed, 57 insertions(+), 57 deletions(-)

diff --git a/docs/guidance/publication.md b/docs/guidance/publication.md
index ff9885f..0f217ba 100644
--- a/docs/guidance/publication.md
+++ b/docs/guidance/publication.md
@@ -137,7 +137,7 @@ libcoveofds jsontogeojson network-package.json nodes.geojson spans.geojson
 To convert data to CSV format:
 
 - [Install Flatten Tool](https://flatten-tool.readthedocs.io/en/latest/getting-started/#getting-started)
-- Download the [network schema](../../schema/network-schema.json)
+- Download the [network schema](../_readthedocs/html/network-schema.json)
 - If your data is a [JSON Lines file](../reference/publication_formats/json.md#streaming-option), segment it into appropriately sized [network packages](../reference/publication_formats/json.md#small-files-and-api-responses-option)
 - Run the following command for each network package:
 
diff --git a/docs/primer/scopeandkeyconcepts.md b/docs/primer/scopeandkeyconcepts.md
index ab8f493..a383767 100644
--- a/docs/primer/scopeandkeyconcepts.md
+++ b/docs/primer/scopeandkeyconcepts.md
@@ -62,7 +62,7 @@ In a fully integrated model, one actor takes on all three roles, whilst in open
 
 OFDS defines a network as:
 
-```{jsoninclude-quote} ../../schema/network-schema.json
+```{jsoninclude-quote} ../_readthedocs/html/network-schema.json
 :jsonpointer: /description
 ```
 
@@ -72,7 +72,7 @@ OFDS defines a network as:
 
 OFDS defines a node as:
 
-```{jsoninclude-quote} ../../schema/network-schema.json
+```{jsoninclude-quote} ../_readthedocs/html/network-schema.json
 :jsonpointer: /$defs/Node/description
 ```
 
@@ -84,7 +84,7 @@ For more information about nodes, see the [Node reference](../reference/schema.m
 
 OFDS defines a span as:
 
-```{jsoninclude-quote} ../../schema/network-schema.json
+```{jsoninclude-quote} ../_readthedocs/html/network-schema.json
 :jsonpointer: /$defs/Span/description
 ```
 
diff --git a/docs/reference/identifiers.md b/docs/reference/identifiers.md
index b2246ad..2385aa7 100644
--- a/docs/reference/identifiers.md
+++ b/docs/reference/identifiers.md
@@ -33,7 +33,7 @@ To ensure that an organisation's `.identifier` is globally unique, it has two co
 
 :::{tab-item} Schema
 
-```{jsonschema} ../../schema/network-schema.json
+```{jsonschema} ../_readthedocs/html/network-schema.json
 :pointer: /$defs/Organisation
 :include: identifier/scheme,identifier/id
 ```
diff --git a/docs/reference/publication_formats/csv.md b/docs/reference/publication_formats/csv.md
index 5148bee..3063a5e 100644
--- a/docs/reference/publication_formats/csv.md
+++ b/docs/reference/publication_formats/csv.md
@@ -90,7 +90,7 @@ This table is related to the following tables:
 
 The fields in this table are listed below. You can also download an [example CSV file](../../../examples/csv/networks.csv) or a [blank template](../../../examples/csv/template/networks.csv) for this table.
 
-```{jsonschema} ../../../schema/network-schema.json
+```{jsonschema} ../../_readthedocs/html/network-schema.json
 :include: id,name,website,publisher,publicationDate,collectionDate,crs,accuracy,accuracyDetails,language
 :nocrossref:
 ```
@@ -105,7 +105,7 @@ This table is related to the following tables:
 
 The fields in this table are listed below. You can also download an [example CSV file](../../../examples/csv/nodes.csv) or a [blank template](../../../examples/csv/template/nodes.csv) for this table.
 
-```{jsonschema} ../../../schema/network-schema.json
+```{jsonschema} ../../_readthedocs/html/network-schema.json
 :include: id,nodes/0/id,nodes/0/name,nodes/0/phase,nodes/0/status,nodes/0/location,nodes/0/address,nodes/0/type,nodes/0/accessPoint,nodes/0/power,nodes/0/technologies,nodes/0/physicalInfrastructureProvider
 :collapse: nodes/0/location
 :nocrossref:
@@ -119,7 +119,7 @@ This table is related to the following tables:
 
 The fields in this table are listed below. You can also download an [example CSV file](../../../examples/csv/nodes_internationalConnections.csv) or a [blank template](../../../examples/csv/template/nodes_internationalConnections.csv) for this table.
 
-```{jsonschema} ../../../schema/network-schema.json
+```{jsonschema} ../../_readthedocs/html/network-schema.json
 :include: id,nodes/0/id,nodes/0/internationalConnections/0/streetAddress,nodes/0/internationalConnections/0/locality,nodes/0/internationalConnections/0/region,nodes/0/internationalConnections/0/postalCode,nodes/0/internationalConnections/0/country
 :nocrossref:
 ```
@@ -132,7 +132,7 @@ This table is related to the following tables:
 
 The fields in this table are listed below. You can also download an [example CSV file](../../../examples/csv/nodes_networkProviders.csv) or a [blank template](../../../examples/csv/template/nodes_networkProviders.csv) for this table.
 
-```{jsonschema} ../../../schema/network-schema.json
+```{jsonschema} ../../_readthedocs/html/network-schema.json
 :include: id,nodes/0/id,nodes/0/networkProviders/0/id,nodes/0/networkProviders/0/name
 :nocrossref:
 ```
@@ -146,7 +146,7 @@ This table is related to the following tables:
 
 The fields in this table are listed below. You can also download an [example CSV file](../../../examples/csv/spans.csv) or a [blank template](../../../examples/csv/template/spans.csv) for this table.
 
-```{jsonschema} ../../../schema/network-schema.json
+```{jsonschema} ../../_readthedocs/html/network-schema.json
 :include: id,spans/0/id,spans/0/name,spans/0/phase,spans/0/status,spans/0/readyForServiceDate,spans/0/start,spans/0/end,spans/0/directed,spans/0/route,spans/0/physicalInfrastructureProvider,spans/0/supplier,spans/0/transmissionMedium,spans/0/deployment,spans/0/deploymentDetails,spans/0/darkFibre,spans/0/fibreType,spans/0/fibreTypeDetails,spans/0/fibreCount,spans/0/fibreLength,spans/0/technologies,spans/0/capacity,spans/0/capacityDetails,spans/0/countries
 :collapse: spans/0/route
 :nocrossref:
@@ -160,7 +160,7 @@ This table is related to the following tables:
 
 The fields in this table are listed below. You can also download an [example CSV file](../../../examples/csv/spans_networkProviders.csv) or a [blank template](../../../examples/csv/template/spans_networkProviders.csv) for this table.
 
-```{jsonschema} ../../../schema/network-schema.json
+```{jsonschema} ../../_readthedocs/html/network-schema.json
 :include: id,spans/0/id,spans/0/networkProviders/0/id,spans/0/networkProviders/0/name
 :nocrossref:
 ```
@@ -174,7 +174,7 @@ This table is related to the following tables:
 
 The fields in this table are listed below. You can also download an [example CSV file](../../../examples/csv/phases.csv) or a [blank template](../../../examples/csv/template/phases.csv) for this table.
 
-```{jsonschema} ../../../schema/network-schema.json
+```{jsonschema} ../../_readthedocs/html/network-schema.json
 :include: id,phases/0/id,phases/0/name,phases/0/description
 :nocrossref:
 ```
@@ -187,7 +187,7 @@ This table is related to the following tables:
 
 The fields in this table are listed below. You can also download an [example CSV file](../../../examples/csv/phases_funders.csv) or a [blank template](../../../examples/csv/template/phases_funders.csv) for this table.
 
-```{jsonschema} ../../../schema/network-schema.json
+```{jsonschema} ../../_readthedocs/html/network-schema.json
 :include: id,phases/0/id,phases/0/funders/0/id,phases/0/funders/0/name
 :nocrossref:
 ```
@@ -200,7 +200,7 @@ This table is related to the following tables:
 
 The fields in this table are listed below. You can also download an [example CSV file](../../../examples/csv/organisations.csv) or a [blank template](../../../examples/csv/template/organisations.csv) for this table.
 
-```{jsonschema} ../../../schema/network-schema.json
+```{jsonschema} ../../_readthedocs/html/network-schema.json
 :include: id,organisations/0/id,organisations/0/name,organisations/0/identifier,organisations/0/country,organisations/0/roles,organisations/0/roleDetails,organisations/0/website,organisations/0/logo
 :nocrossref:
 ```
@@ -215,7 +215,7 @@ This table is related to the following tables:
 
 The fields in this table are listed below. You can also download an [example CSV file](../../../examples/csv/contracts.csv) or a [blank template](../../../examples/csv/template/contracts.csv) for this table.
 
-```{jsonschema} ../../../schema/network-schema.json
+```{jsonschema} ../../_readthedocs/html/network-schema.json
 :include: id,contracts/0/id,contracts/0/title,contracts/0/description,contracts/0/type,contracts/0/value,contracts/0/dateSigned
 :nocrossref:
 ```
@@ -228,7 +228,7 @@ This table is related to the following tables:
 
 The fields in this table are listed below. You can also download an [example CSV file](../../../examples/csv/contracts_documents.csv) or a [blank template](../../../examples/csv/template/contracts_documents.csv) for this table.
 
-```{jsonschema} ../../../schema/network-schema.json
+```{jsonschema} ../../_readthedocs/html/network-schema.json
 :include: id,contracts/0/id,contracts/0/documents/0/title,contracts/0/documents/0/description,contracts/0/documents/0/url,contracts/0/documents/0/format
 :nocrossref:
 ```
@@ -241,7 +241,7 @@ This table is related to the following tables:
 
 The fields in this table are listed below. You can also download an [example CSV file](../../../examples/csv/contracts_relatedPhases.csv) or a [blank template](../../../examples/csv/template/contracts_relatedPhases.csv) for this table.
 
-```{jsonschema} ../../../schema/network-schema.json
+```{jsonschema} ../../_readthedocs/html/network-schema.json
 :include: id,contracts/0/id,contracts/0/relatedPhases/0/id,contracts/0/relatedPhases/0/name
 :nocrossref:
 ```
@@ -254,7 +254,7 @@ This table is related to the following tables:
 
 The fields in this table are listed below. You can also download an [example CSV file](../../../examples/csv/links.csv) or a [blank template](../../../examples/csv/template/links.csv) for this table.
 
-```{jsonschema} ../../../schema/network-schema.json
+```{jsonschema} ../../_readthedocs/html/network-schema.json
 :include: id,links/0/href,links/0/rel
 :nocrossref:
 ```
diff --git a/docs/reference/schema.md b/docs/reference/schema.md
index 9100315..07ce58c 100644
--- a/docs/reference/schema.md
+++ b/docs/reference/schema.md
@@ -12,7 +12,7 @@ The schema provides the authoritative definition of the structure of Open Fibre
 
 For this version of OFDS, the canonical URL of the schema is [https://raw.githubusercontent.com/Open-Telecoms-Data/open-fibre-data-standard/0\_\_3\_\_0/schema/network-schema.json](https://raw.githubusercontent.com/Open-Telecoms-Data/open-fibre-data-standard/0__3__0/schema/network-schema.json). Use the canonical URL to make sure that your software, documentation or other resources refer to the specific version of the schema with which they were tested.
 
-This page presents the schema in an [interactive browser](#browser) and in [reference tables](#reference-tables) with additional information in paragraphs. You can also download the canonical version of the schema as [JSON Schema](../../schema/network-schema.json) or download it as a [CSV spreadsheet](../../schema/network-schema.csv).
+This page presents the schema in an [interactive browser](#browser) and in [reference tables](#reference-tables) with additional information in paragraphs. You can also download the canonical version of the schema as [JSON Schema](../_readthedocs/html/network-schema.json) or download it as a [CSV spreadsheet](../../schema/network-schema.csv).
 
 ```{note}
    If any conflicts are found between the text on this page and the text within the schema, the text within the schema takes precedence.
@@ -44,7 +44,7 @@ In addition to the above sections, there are several top-level metadata fields:
 
 :::{tab-item} Schema
 
-```{jsonschema} ../../schema/network-schema.json
+```{jsonschema} ../_readthedocs/html/network-schema.json
 :collapse: nodes,spans,phases,organisations,contracts,crs,links
 :addtargets:
 ```
@@ -101,7 +101,7 @@ This section lists each component in the OFDS schema. Some components are reused
 
 `Node` is defined as:
 
-```{jsoninclude-quote} ../../schema/network-schema.json
+```{jsoninclude-quote} ../_readthedocs/html/network-schema.json
 :jsonpointer: /$defs/Node/description
 ```
 
@@ -115,7 +115,7 @@ Each `Node` has the following fields:
 
 :::{tab-item} Schema
 
-```{jsonschema} ../../schema/network-schema.json
+```{jsonschema} ../_readthedocs/html/network-schema.json
 :pointer: /$defs/Node
 :collapse: id,name,phase,status,location,address,type,accessPoint,internationalConnections,power,technologies,physicalInfrastructureProvider,networkProviders
 :addtargets:
@@ -139,7 +139,7 @@ Each `Node` has the following fields:
 
 `Span` is defined as:
 
-```{jsoninclude-quote} ../../schema/network-schema.json
+```{jsoninclude-quote} ../_readthedocs/html/network-schema.json
 :jsonpointer: /$defs/Span/description
 ```
 
@@ -153,7 +153,7 @@ Each `Span` has the following fields:
 
 :::{tab-item} Schema
 
-```{jsonschema} ../../schema/network-schema.json
+```{jsonschema} ../_readthedocs/html/network-schema.json
 :pointer: /$defs/Span
 :collapse: id,name,phase,status,readyForServiceDate,start,end,directed,route,physicalInfrastructureProvider,networkProviders,supplier,transmissionMedium,deployment,deploymentDetails,darkFibre,fibreType,fibreTypeDetails,fibreCount,fibreLength,technologies,capacity,capacityDetails,countries
 :addtargets:
@@ -177,7 +177,7 @@ Each `Span` has the following fields:
 
 `Phase` is defined as:
 
-```{jsoninclude-quote} ../../schema/network-schema.json
+```{jsoninclude-quote} ../_readthedocs/html/network-schema.json
 :jsonpointer: /$defs/Phase/description
 ```
 
@@ -191,7 +191,7 @@ Each `Phase` has the following fields:
 
 :::{tab-item} Schema
 
-```{jsonschema} ../../schema/network-schema.json
+```{jsonschema} ../_readthedocs/html/network-schema.json
 :pointer: /$defs/Phase
 :collapse: id,name,description,funders
 :addtargets:
@@ -215,7 +215,7 @@ Each `Phase` has the following fields:
 
 `Organisation` is defined as:
 
-```{jsoninclude-quote} ../../schema/network-schema.json
+```{jsoninclude-quote} ../_readthedocs/html/network-schema.json
 :jsonpointer: /$defs/Organisation/description
 ```
 
@@ -229,7 +229,7 @@ Each `Organisation` has the following fields:
 
 :::{tab-item} Schema
 
-```{jsonschema} ../../schema/network-schema.json
+```{jsonschema} ../_readthedocs/html/network-schema.json
 :pointer: /$defs/Organisation
 :collapse: id,name,identifier,country,roles,roleDetails,website,logo
 :addtargets:
@@ -253,7 +253,7 @@ Each `Organisation` has the following fields:
 
 `Contract` is defined as:
 
-```{jsoninclude-quote} ../../schema/network-schema.json
+```{jsoninclude-quote} ../_readthedocs/html/network-schema.json
 :jsonpointer: /$defs/Contract/description
 ```
 
@@ -267,7 +267,7 @@ Each `Contract` has the following fields:
 
 :::{tab-item} Schema
 
-```{jsonschema} ../../schema/network-schema.json
+```{jsonschema} ../_readthedocs/html/network-schema.json
 :pointer: /$defs/Contract
 :collapse: id,title,description,type,value,dateSigned,documents,relatedPhases
 :addtargets:
@@ -291,7 +291,7 @@ Each `Contract` has the following fields:
 
 `Geometry` is defined as:
 
-```{jsoninclude-quote} ../../schema/network-schema.json
+```{jsoninclude-quote} ../_readthedocs/html/network-schema.json
 :jsonpointer: /$defs/Geometry/description
 ```
 
@@ -308,7 +308,7 @@ Each `Geometry` has the following fields:
 
 :::{tab-item} Schema
 
-```{jsonschema} ../../schema/network-schema.json
+```{jsonschema} ../_readthedocs/html/network-schema.json
 :pointer: /$defs/Geometry
 :collapse: type,coordinates
 :addtargets:
@@ -338,7 +338,7 @@ Each `Geometry` has the following fields:
 
 `OrganisationReference` is defined as:
 
-```{jsoninclude-quote} ../../schema/network-schema.json
+```{jsoninclude-quote} ../_readthedocs/html/network-schema.json
 :jsonpointer: /$defs/OrganisationReference/description
 ```
 
@@ -357,7 +357,7 @@ Each `OrganisationReference` has the following fields:
 
 :::{tab-item} Schema
 
-```{jsonschema} ../../schema/network-schema.json
+```{jsonschema} ../_readthedocs/html/network-schema.json
 :pointer: /$defs/OrganisationReference
 :collapse: id,name
 :addtargets:
@@ -411,7 +411,7 @@ Each `OrganisationReference` has the following fields:
 
 `PhaseReference` is defined as:
 
-```{jsoninclude-quote} ../../schema/network-schema.json
+```{jsoninclude-quote} ../_readthedocs/html/network-schema.json
 :jsonpointer: /$defs/PhaseReference/description
 ```
 
@@ -427,7 +427,7 @@ Each `PhaseReference` has the following fields:
 
 :::{tab-item} Schema
 
-```{jsonschema} ../../schema/network-schema.json
+```{jsonschema} ../_readthedocs/html/network-schema.json
 :pointer: /$defs/PhaseReference
 :collapse: id,name
 :addtargets:
@@ -463,7 +463,7 @@ Each `PhaseReference` has the following fields:
 
 `Address` is defined as:
 
-```{jsoninclude-quote} ../../schema/network-schema.json
+```{jsoninclude-quote} ../_readthedocs/html/network-schema.json
 :jsonpointer: /$defs/Address/description
 ```
 
@@ -478,7 +478,7 @@ Each `Address` has the following fields:
 
 :::{tab-item} Schema
 
-```{jsonschema} ../../schema/network-schema.json
+```{jsonschema} ../_readthedocs/html/network-schema.json
 :pointer: /$defs/Address
 :collapse: streetAddress,locality,region,postalCode,country
 :addtargets:
@@ -508,7 +508,7 @@ Each `Address` has the following fields:
 
 `Value` is defined as:
 
-```{jsoninclude-quote} ../../schema/network-schema.json
+```{jsoninclude-quote} ../_readthedocs/html/network-schema.json
 :jsonpointer: /$defs/Value/description
 ```
 
@@ -522,7 +522,7 @@ Each `Value` has the following fields:
 
 :::{tab-item} Schema
 
-```{jsonschema} ../../schema/network-schema.json
+```{jsonschema} ../_readthedocs/html/network-schema.json
 :pointer: /$defs/Value
 :collapse: amount,currency
 :addtargets:
@@ -546,7 +546,7 @@ Each `Value` has the following fields:
 
 `Document` is defined as:
 
-```{jsoninclude-quote} ../../schema/network-schema.json
+```{jsoninclude-quote} ../_readthedocs/html/network-schema.json
 :jsonpointer: /$defs/Document/description
 ```
 
@@ -560,7 +560,7 @@ Each `Document` has the following fields:
 
 :::{tab-item} Schema
 
-```{jsonschema} ../../schema/network-schema.json
+```{jsonschema} ../_readthedocs/html/network-schema.json
 :pointer: /$defs/Document
 :collapse: title,description,url,format
 :addtargets:
@@ -584,7 +584,7 @@ Each `Document` has the following fields:
 
 `Identifier` is defined as:
 
-```{jsoninclude-quote} ../../schema/network-schema.json
+```{jsoninclude-quote} ../_readthedocs/html/network-schema.json
 :jsonpointer: /$defs/Identifier/description
 ```
 
@@ -598,7 +598,7 @@ Each `Identifier` has the following fields:
 
 :::{tab-item} Schema
 
-```{jsonschema} ../../schema/network-schema.json
+```{jsonschema} ../_readthedocs/html/network-schema.json
 :pointer: /$defs/Identifier
 :collapse: id,scheme,legalName,uri
 :addtargets:
@@ -641,7 +641,7 @@ For more information, see [How to transform coordinates to the correct coordinat
 
 `CoordinateReferenceSystem` is defined as:
 
-```{jsoninclude-quote} ../../schema/network-schema.json
+```{jsoninclude-quote} ../_readthedocs/html/network-schema.json
 :jsonpointer: /$defs/CoordinateReferenceSystem/description
 ```
 
@@ -655,7 +655,7 @@ Each `CoordinateReferenceSystem` has the following fields:
 
 :::{tab-item} Schema
 
-```{jsonschema} ../../schema/network-schema.json
+```{jsonschema} ../_readthedocs/html/network-schema.json
 :pointer: /$defs/CoordinateReferenceSystem
 :collapse: name,uri
 :addtargets:
@@ -679,7 +679,7 @@ Each `CoordinateReferenceSystem` has the following fields:
 
 `Link` is defined as:
 
-```{jsoninclude-quote} ../../schema/network-schema.json
+```{jsoninclude-quote} ../_readthedocs/html/network-schema.json
 :jsonpointer: /$defs/Link/description
 ```
 
@@ -693,7 +693,7 @@ Each `Link` has the following fields:
 
 :::{tab-item} Schema
 
-```{jsonschema} ../../schema/network-schema.json
+```{jsonschema} ../_readthedocs/html/network-schema.json
 :pointer: /$defs/Link
 :collapse: href,rel
 :addtargets:
@@ -717,7 +717,7 @@ Each `Link` has the following fields:
 
 `FibreTypeDetails` is defined as:
 
-```{jsoninclude-quote} ../../schema/network-schema.json
+```{jsoninclude-quote} ../_readthedocs/html/network-schema.json
 :jsonpointer: /$defs/FibreTypeDetails/description
 ```
 
@@ -731,7 +731,7 @@ Each `FibreTypeDetails` has the following fields:
 
 :::{tab-item} Schema
 
-```{jsonschema} ../../schema/network-schema.json
+```{jsonschema} ../_readthedocs/html/network-schema.json
 :pointer: /$defs/FibreTypeDetails
 :collapse: fibreSubtype,description
 :addtargets:
@@ -755,7 +755,7 @@ Each `FibreTypeDetails` has the following fields:
 
 `DeploymentDetails` is defined as:
 
-```{jsoninclude-quote} ../../schema/network-schema.json
+```{jsoninclude-quote} ../_readthedocs/html/network-schema.json
 :jsonpointer: /$defs/DeploymentDetails/description
 ```
 
@@ -769,7 +769,7 @@ Each `DeploymentDetails` has the following fields:
 
 :::{tab-item} Schema
 
-```{jsonschema} ../../schema/network-schema.json
+```{jsonschema} ../_readthedocs/html/network-schema.json
 :pointer: /$defs/DeploymentDetails
 :collapse: description
 :addtargets:
@@ -793,7 +793,7 @@ Each `DeploymentDetails` has the following fields:
 
 `CapacityDetails` is defined as:
 
-```{jsoninclude-quote} ../../schema/network-schema.json
+```{jsoninclude-quote} ../_readthedocs/html/network-schema.json
 :jsonpointer: /$defs/CapacityDetails/description
 ```
 
@@ -807,7 +807,7 @@ Each `CapacityDetails` has the following fields:
 
 :::{tab-item} Schema
 
-```{jsonschema} ../../schema/network-schema.json
+```{jsonschema} ../_readthedocs/html/network-schema.json
 :pointer: /$defs/CapacityDetails
 :collapse: description
 :addtargets:
diff --git a/manage.py b/manage.py
index 94892f9..98308fa 100755
--- a/manage.py
+++ b/manage.py
@@ -205,7 +205,7 @@ def generate_csv_reference_markdown(table, schema, parents=None, depth=2):
 
   # Generate jsonschema directive
   markdown[table]['content'].extend([
-    "```{jsonschema} ../../../schema/network-schema.json\n"
+    "```{jsonschema} ../../_readthedocs/html/network-schema.json\n"
     f":include: {','.join(include_pointers)}\n"
   ])
 
@@ -428,7 +428,7 @@ def update_schema_docs(schema):
       # Add description
       definition["content"].extend([
           f"`{defn}` is defined as:\n\n",
-          "```{jsoninclude-quote} ../../schema/network-schema.json\n",
+          "```{jsoninclude-quote} ../_readthedocs/html/network-schema.json\n",
           f":jsonpointer: /$defs/{defn}/description\n",
           "```\n\n"
       ])
@@ -463,7 +463,7 @@ def update_schema_docs(schema):
           f"\nEach `{defn}` has the following fields:\n\n", 
           "::::{tab-set}\n\n",
           ":::{tab-item} Schema\n\n",
-          "```{jsonschema} ../../schema/network-schema.json\n",
+          "```{jsonschema} ../_readthedocs/html/network-schema.json\n",
           f":pointer: /$defs/{defn}\n",
           f":collapse: {','.join(definition['properties'].keys())}\n",
           ":addtargets:\n",

From 9e9d39d2b8a5014f2516b8d8c1695ddff846635f Mon Sep 17 00:00:00 2001
From: Duncan Dewhurst <duncan.dewhurst@opendataservices.coop>
Date: Tue, 11 Jun 2024 16:43:33 +0100
Subject: [PATCH 4/4] network-schema: Remove html suffix from documentation
 links

---
 schema/network-schema.json | 50 +++++++++++++++++++-------------------
 1 file changed, 25 insertions(+), 25 deletions(-)

diff --git a/schema/network-schema.json b/schema/network-schema.json
index f3b62ad..6a90d9f 100644
--- a/schema/network-schema.json
+++ b/schema/network-schema.json
@@ -11,7 +11,7 @@
   "properties": {
     "id": {
       "title": "Identifier",
-      "description": "A universally unique identifier for this network, as defined by [RFC 4122](https://datatracker.ietf.org/doc/html/rfc4122). For more information, see the [identifier reference](https://open-fibre-data-standard.readthedocs.io/en/{{version}}/reference/identifiers.html).",
+      "description": "A universally unique identifier for this network, as defined by [RFC 4122](https://datatracker.ietf.org/doc/html/rfc4122). For more information, see the [identifier reference](https://open-fibre-data-standard.readthedocs.io/en/{{version}}/reference/identifiers).",
       "format": "uuid",
       "type": "string"
     },
@@ -23,7 +23,7 @@
     },
     "nodes": {
       "title": "Nodes",
-      "description": "Information about the nodes that belong to this network. Information about nodes should be embedded in this field unless:\n\n* The network is too large to load in to memory, in which case a link to a streamable bulk nodes file may be provided in `.links`\n* The data is published via an API and the network is too large to return in a single API response, in which case a link to a paginated nodes endpoint may be provided in `.links`.\n\nFor more information, see [how to format data for publication](https://open-fibre-data-standard.readthedocs.io/en/{{version}}/guidance/publication.html#how-to-format-data-for-publication).",
+      "description": "Information about the nodes that belong to this network. Information about nodes should be embedded in this field unless:\n\n* The network is too large to load in to memory, in which case a link to a streamable bulk nodes file may be provided in `.links`\n* The data is published via an API and the network is too large to return in a single API response, in which case a link to a paginated nodes endpoint may be provided in `.links`.\n\nFor more information, see [how to format data for publication](https://open-fibre-data-standard.readthedocs.io/en/{{version}}/guidance/publication#how-to-format-data-for-publication).",
       "type": "array",
       "items": {
         "$ref": "#/$defs/Node"
@@ -33,7 +33,7 @@
     },
     "spans": {
       "title": "Spans",
-      "description": "Information about the spans that belong to this network. Information about spans should be embedded in this field unless:\n\n* The network is too large to load in to memory, in which case a link to a streamable bulk spans file may be provided in `.links`\n* The data is published via an API and the network is too large to return in a single API response, in which case a link to a paginated spans endpoint may be provided in `.links`.\n\nFor more information, see [how to format data for publication](https://open-fibre-data-standard.readthedocs.io/en/{{version}}/guidance/publication.html#how-to-format-data-for-publication).",
+      "description": "Information about the spans that belong to this network. Information about spans should be embedded in this field unless:\n\n* The network is too large to load in to memory, in which case a link to a streamable bulk spans file may be provided in `.links`\n* The data is published via an API and the network is too large to return in a single API response, in which case a link to a paginated spans endpoint may be provided in `.links`.\n\nFor more information, see [how to format data for publication](https://open-fibre-data-standard.readthedocs.io/en/{{version}}/guidance/publication#how-to-format-data-for-publication).",
       "type": "array",
       "items": {
         "$ref": "#/$defs/Span"
@@ -129,7 +129,7 @@
     },
     "language": {
       "title": "Language",
-      "description": "The default language of this network,from the open [language codelist](https://open-fibre-data-standard.readthedocs.io/en/{{version}}/reference/codelists.html#language). A [BCP47 language tag](https://www.w3.org/International/articles/language-tags/) is allowed, if there is a user need for the additional information.",
+      "description": "The default language of this network,from the open [language codelist](https://open-fibre-data-standard.readthedocs.io/en/{{version}}/reference/codelists#language). A [BCP47 language tag](https://www.w3.org/International/articles/language-tags/) is allowed, if there is a user need for the additional information.",
       "type": "string",
       "codelist": "language.csv",
       "openCodelist": true,
@@ -137,7 +137,7 @@
     },
     "links": {
       "title": "Links",
-      "description": "Links to related resources. The first item in the links array must be a link to the canonical JSON schema that describes the structure of the data. Links to API endpoints for nodes and spans should be provided when a network is too large to return in a single API response and links to bulk files should be provided when a network is too large to load into memory, for more information, see [how to publish large networks](https://open-fibre-data-standard.readthedocs.io/en/{{version}}/guidance/publication.html#how-to-publish-large-networks).",
+      "description": "Links to related resources. The first item in the links array must be a link to the canonical JSON schema that describes the structure of the data. Links to API endpoints for nodes and spans should be provided when a network is too large to return in a single API response and links to bulk files should be provided when a network is too large to load into memory, for more information, see [how to publish large networks](https://open-fibre-data-standard.readthedocs.io/en/{{version}}/guidance/publication#how-to-publish-large-networks).",
       "type": "array",
       "prefixItems": [
         {
@@ -186,7 +186,7 @@
         },
         "status": {
           "title": "Status",
-          "description": "The status of this node, from the closed [nodeStatus codelist](https://open-fibre-data-standard.readthedocs.io/en/{{version}}/reference/codelists.html#nodestatus).",
+          "description": "The status of this node, from the closed [nodeStatus codelist](https://open-fibre-data-standard.readthedocs.io/en/{{version}}/reference/codelists#nodestatus).",
           "type": "string",
           "codelist": "nodeStatus.csv",
           "openCodelist": false,
@@ -201,7 +201,7 @@
         },
         "location": {
           "title": "Node location",
-          "description": "In the [JSON publication format](https://open-fibre-data-standard.readthedocs.io/en/{{version}}/reference/publication_formats/json.html), a GeoJSON [Point](https://datatracker.ietf.org/doc/html/rfc7946#section-3.1.4) geometry describing the physical location of this node. In the [CSV publication format](https://open-fibre-data-standard.readthedocs.io/en/{{version}}/reference/publication_formats/csv.html), a [well-known text](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry) POINT geometry.",
+          "description": "In the [JSON publication format](https://open-fibre-data-standard.readthedocs.io/en/{{version}}/reference/publication_formats/json), a GeoJSON [Point](https://datatracker.ietf.org/doc/html/rfc7946#section-3.1.4) geometry describing the physical location of this node. In the [CSV publication format](https://open-fibre-data-standard.readthedocs.io/en/{{version}}/reference/publication_formats/csv), a [well-known text](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry) POINT geometry.",
           "$ref": "#/$defs/Geometry"
         },
         "address": {
@@ -211,7 +211,7 @@
         },
         "type": {
           "title": "Node type",
-          "description": "The type of this node, from the open [nodeType codelist](https://open-fibre-data-standard.readthedocs.io/en/{{version}}/reference/codelists.html#nodetype). For nodes with multiple network providers, the union of the node types for each provider.",
+          "description": "The type of this node, from the open [nodeType codelist](https://open-fibre-data-standard.readthedocs.io/en/{{version}}/reference/codelists#nodetype). For nodes with multiple network providers, the union of the node types for each provider.",
           "type": "array",
           "items": {
             "type": [
@@ -247,7 +247,7 @@
         },
         "technologies": {
           "title": "Technologies",
-          "description": "The active technologies used at this node, from the open [nodeTechnologies codelist](https://open-fibre-data-standard.readthedocs.io/en/{{version}}/reference/codelists.html#nodetechnologies). For nodes with multiple network providers, the union of the active technologies used by each provider.",
+          "description": "The active technologies used at this node, from the open [nodeTechnologies codelist](https://open-fibre-data-standard.readthedocs.io/en/{{version}}/reference/codelists#nodetechnologies). For nodes with multiple network providers, the union of the active technologies used by each provider.",
           "type": "array",
           "items": {
             "type": [
@@ -306,7 +306,7 @@
         },
         "status": {
           "title": "Span status",
-          "description": "The status of the network infrastructure for this span, from the closed [spanStatus codelist](https://open-fibre-data-standard.readthedocs.io/en/{{version}}/reference/codelists.html#spanstatus).",
+          "description": "The status of the network infrastructure for this span, from the closed [spanStatus codelist](https://open-fibre-data-standard.readthedocs.io/en/{{version}}/reference/codelists#spanstatus).",
           "type": "string",
           "codelist": "spanStatus.csv",
           "openCodelist": false,
@@ -346,7 +346,7 @@
         },
         "route": {
           "title": "Span route",
-          "description": "In the [JSON publication format](https://open-fibre-data-standard.readthedocs.io/en/{{version}}/reference/publication_formats/json.html), a GeoJSON [LineString](https://datatracker.ietf.org/doc/html/rfc7946#section-3.1.4) geometry describing the route of this span. In the [CSV publication format](https://open-fibre-data-standard.readthedocs.io/en/{{version}}/reference/publication_formats/csv.html), a [well-known text](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry) LINESTRING geometry.",
+          "description": "In the [JSON publication format](https://open-fibre-data-standard.readthedocs.io/en/{{version}}/reference/publication_formats/json), a GeoJSON [LineString](https://datatracker.ietf.org/doc/html/rfc7946#section-3.1.4) geometry describing the route of this span. In the [CSV publication format](https://open-fibre-data-standard.readthedocs.io/en/{{version}}/reference/publication_formats/csv), a [well-known text](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry) LINESTRING geometry.",
           "$ref": "#/$defs/Geometry"
         },
         "physicalInfrastructureProvider": {
@@ -372,7 +372,7 @@
         },
         "transmissionMedium": {
           "title": "Transmission medium",
-          "description": "The physical media of this span, from the closed [transmissionMedium codelist](https://open-fibre-data-standard.readthedocs.io/en/{{version}}/reference/codelists.html#transmissionmedium).",
+          "description": "The physical media of this span, from the closed [transmissionMedium codelist](https://open-fibre-data-standard.readthedocs.io/en/{{version}}/reference/codelists#transmissionmedium).",
           "type": "array",
           "items": {
             "type": [
@@ -393,7 +393,7 @@
         },
         "deployment": {
           "title": "Deployment",
-          "description": "The physical deployment of this span, from the closed [deployment codelist](https://open-fibre-data-standard.readthedocs.io/en/{{version}}/reference/codelists.html#deployment). Further details of this span's deployment can be provided in `.deploymentDetails`.",
+          "description": "The physical deployment of this span, from the closed [deployment codelist](https://open-fibre-data-standard.readthedocs.io/en/{{version}}/reference/codelists#deployment). Further details of this span's deployment can be provided in `.deploymentDetails`.",
           "type": "array",
           "items": {
             "type": [
@@ -423,7 +423,7 @@
         },
         "fibreType": {
           "title": "Fibre type",
-          "description": "The type of fibre used in this span, from the closed [fibreType codelist](https://open-fibre-data-standard.readthedocs.io/en/{{version}}/reference/codelists.html#fibretype). Further details of the span's fibre type can be provided in `.fibreTypeDetails`.",
+          "description": "The type of fibre used in this span, from the closed [fibreType codelist](https://open-fibre-data-standard.readthedocs.io/en/{{version}}/reference/codelists#fibretype). Further details of the span's fibre type can be provided in `.fibreTypeDetails`.",
           "type": "string",
           "codelist": "fibreType.csv",
           "openCodelist": false,
@@ -456,7 +456,7 @@
         },
         "technologies": {
           "title": "Technologies",
-          "description": "The active technologies used on this span, from the open [spanTechnologies codelist](https://open-fibre-data-standard.readthedocs.io/en/{{version}}/reference/codelists.html#spantechnologies). For spans with multiple network providers, the union of the active technologies used by each provider.",
+          "description": "The active technologies used on this span, from the open [spanTechnologies codelist](https://open-fibre-data-standard.readthedocs.io/en/{{version}}/reference/codelists#spantechnologies). For spans with multiple network providers, the union of the active technologies used by each provider.",
           "type": "array",
           "items": {
             "type": [
@@ -482,7 +482,7 @@
         },
         "countries": {
           "title": "Countries",
-          "description": "The countries in which this span is physically located, from the closed [country codelist](https://open-fibre-data-standard.readthedocs.io/en/{{version}}/reference/codelists.html#country).",
+          "description": "The countries in which this span is physically located, from the closed [country codelist](https://open-fibre-data-standard.readthedocs.io/en/{{version}}/reference/codelists#country).",
           "type": "array",
           "items": {
             "type": [
@@ -816,7 +816,7 @@
         },
         "country": {
           "title": "Country",
-          "description": "The country in which this organisation is legally registered, from the closed [country codelist](https://open-fibre-data-standard.readthedocs.io/en/{{version}}/reference/codelists.html#country).",
+          "description": "The country in which this organisation is legally registered, from the closed [country codelist](https://open-fibre-data-standard.readthedocs.io/en/{{version}}/reference/codelists#country).",
           "type": "string",
           "codelist": "country.csv",
           "openCodelist": false,
@@ -1075,7 +1075,7 @@
         },
         "roles": {
           "title": "Roles",
-          "description": "This organisation's roles in this network, from the open [organisationRole codelist](https://open-fibre-data-standard.readthedocs.io/en/{{version}}/reference/codelists.html#organisationrole). Further details about this organisation's roles can be provided in `.roleDetails`.",
+          "description": "This organisation's roles in this network, from the open [organisationRole codelist](https://open-fibre-data-standard.readthedocs.io/en/{{version}}/reference/codelists#organisationrole). Further details about this organisation's roles can be provided in `.roleDetails`.",
           "type": "array",
           "items": {
             "type": [
@@ -1139,7 +1139,7 @@
         },
         "type": {
           "title": "Contract type",
-          "description": "The type of this contract, from the open [contractType codelist](https://open-fibre-data-standard.readthedocs.io/en/{{version}}/reference/codelists.html#contracttype).",
+          "description": "The type of this contract, from the open [contractType codelist](https://open-fibre-data-standard.readthedocs.io/en/{{version}}/reference/codelists#contracttype).",
           "type": "string",
           "codelist": "contractType.csv",
           "openCodelist": true,
@@ -1190,7 +1190,7 @@
       "properties": {
         "type": {
           "title": "Type",
-          "description": "The [GeoJSON geometry type](https://datatracker.ietf.org/doc/html/rfc7946#section-1.4) that is described by `.coordinates`, from the closed [geometryType codelist](https://open-fibre-data-standard.readthedocs.io/en/{{version}}/reference/codelists.html#geometrytype). This must be 'Point' when referenced by `Node.location`, and 'LineString' when referenced by `Span.route`.",
+          "description": "The [GeoJSON geometry type](https://datatracker.ietf.org/doc/html/rfc7946#section-1.4) that is described by `.coordinates`, from the closed [geometryType codelist](https://open-fibre-data-standard.readthedocs.io/en/{{version}}/reference/codelists#geometrytype). This must be 'Point' when referenced by `Node.location`, and 'LineString' when referenced by `Span.route`.",
           "type": "string",
           "codelist": "geometryType.csv",
           "openCodelist": false,
@@ -1297,7 +1297,7 @@
         },
         "country": {
           "title": "Country",
-          "description": "The country in which the address is physically located, from the closed [country codelist](https://open-fibre-data-standard.readthedocs.io/en/{{version}}/reference/codelists.html#country).",
+          "description": "The country in which the address is physically located, from the closed [country codelist](https://open-fibre-data-standard.readthedocs.io/en/{{version}}/reference/codelists#country).",
           "type": "string",
           "codelist": "country.csv",
           "openCodelist": false,
@@ -1570,7 +1570,7 @@
         },
         "currency": {
           "title": "Currency",
-          "description": "The currency of this value, from the closed [currency codelist](https://open-fibre-data-standard.readthedocs.io/en/{{version}}/reference/codelists.html#currency).",
+          "description": "The currency of this value, from the closed [currency codelist](https://open-fibre-data-standard.readthedocs.io/en/{{version}}/reference/codelists#currency).",
           "type": "string",
           "codelist": "currency.csv",
           "openCodelist": false,
@@ -1910,7 +1910,7 @@
         },
         "format": {
           "title": "Format",
-          "description": "The format of this document, from the open [mediaType codelist](https://open-fibre-data-standard.readthedocs.io/en/{{version}}/reference/codelists.html#mediatype).",
+          "description": "The format of this document, from the open [mediaType codelist](https://open-fibre-data-standard.readthedocs.io/en/{{version}}/reference/codelists#mediatype).",
           "type": "string",
           "codelist": "mediaType.csv",
           "openCodelist": true,
@@ -1932,7 +1932,7 @@
         },
         "scheme": {
           "title": "Scheme",
-          "description": "The register from which the identifier in `.id` is drawn, from the open [organisationIdentifierScheme codelist](https://open-fibre-data-standard.readthedocs.io/en/{{version}}/reference/codelists.html#organisationidentifierscheme).",
+          "description": "The register from which the identifier in `.id` is drawn, from the open [organisationIdentifierScheme codelist](https://open-fibre-data-standard.readthedocs.io/en/{{version}}/reference/codelists#organisationidentifierscheme).",
           "type": "string",
           "codelist": "organisationIdentifierScheme.csv",
           "openCodelist": true,
@@ -1996,7 +1996,7 @@
         },
         "rel": {
           "title": "Link relation type",
-          "description": "The relationship with this related resource, from the open [linkRelationType codelist](https://open-fibre-data-standard.readthedocs.io/en/{{version}}/reference/codelists.html#linkrelationtype). The 'describedby' code must only be used in the first item in the `links` array to link to the schema that describes the structure of the data.",
+          "description": "The relationship with this related resource, from the open [linkRelationType codelist](https://open-fibre-data-standard.readthedocs.io/en/{{version}}/reference/codelists#linkrelationtype). The 'describedby' code must only be used in the first item in the `links` array to link to the schema that describes the structure of the data.",
           "type": "string",
           "codelist": "linkRelationType.csv",
           "openCodelist": true,