Consolidate Errors; Improve json-schema docs

Not great json-schema documentation - but better than it was.
network-wrangler · Oct 9, 2024 · 81dd590 · 81dd590
1 parent cc9dd07
commit 81dd590
Show file tree

Hide file tree

Showing 18 changed files with 446 additions and 91 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -0,0 +1,10 @@
+
+Notable changes and version history.
+
+| Version | Date  | Comment |
+|---------|-------|-------|
+| [v0.3.1](https://github.com/network-wrangler/projectcard/releases/tag/v0.3.1) | 2024-10-07 | Improved resilience of `read_cards()` including ability to handle relative paths. |
+| [v0.3.0](https://github.com/network-wrangler/projectcard/releases/tag/v0.3.0) | 2024-09-27 | Added transit addition and deletion change types. |
+| [v0.2.0](https://github.com/network-wrangler/projectcard/releases/tag/v0.2.0) | 2024-09-08 | Read cards from nested folders. |
+| [v0.1.2](https://github.com/network-wrangler/projectcard/releases/tag/v0.1.2) | 2024-08-05 | - |
+| [v0.1.1](https://github.com/network-wrangler/projectcard/releases/tag/v0.1.1) | 2024-06-20 | Initial release on PyPI |
diff --git a/docs/development.md b/docs/development.md
@@ -133,3 +133,10 @@ mkdocs serve
 !!! tip
 
     Releases must have a unique version number in order to be updated on pypi.
+
+## Changelog
+
+{!
+    include-markdown "../CHANGELOG.md"
+    heading-offset=1
+!}
diff --git a/docs/index.md b/docs/index.md
@@ -84,4 +84,11 @@ But we'd love to make it better! Please report bugs or incorrect/unclear/missing
 
 ## Who-dat?
 
-ProjectCard was developed using resources from the [Metropolitan Transportation Commission](bayareametro.gov), [Metropolitan Council MN](https://metrocouncil.org/), and in-kind time from [UrbanLabs LLC](https://urbanlabs.io) and [WSP](www.wsp.com).  It is currently maintained using in-kind time...so please be patient.
+ProjectCard was developed using resources from the [Metropolitan Transportation Commission](https://www.bayareametro.gov), [Metropolitan Council MN](https://metrocouncil.org/), and in-kind time from [UrbanLabs LLC](https://urbanlabs.io) and [WSP](https://www.wsp.com).  It is currently maintained using in-kind time...so please be patient.
+
+## Release History
+
+{!
+    include-markdown "../CHANGELOG.md"
+    heading-offset=1
+!}
diff --git a/docs/json-schemas.md b/docs/json-schemas.md
@@ -3,4 +3,4 @@
 !!! tip "Find this documentation confusing?"
     Me too.  That's why we spent a bunch more time documenting the [data models](datamodels.md), which read much more nicely - or you can check out the [examples](examples.md).
 
-{{ document_schema(schema_filename="projectcard.json") }}
+{{ document_schema() }}
diff --git a/docs/requirements.txt b/docs/requirements.txt
@@ -1,6 +1,5 @@
 fontawesome_markdown
-json_schema_for_humans
-jsonschema2md
+jsonschema-markdown
 mike
 mkdocs
 mkdocs-autorefs

diff --git a/main.py b/main.py
@@ -15,42 +15,11 @@ def define_env(env):
     """
 
     @env.macro
-    def document_schema(schema_filename: str) -> str:
-        from json_schema_for_humans.generate import generate_from_schema
-        from json_schema_for_humans.generation_configuration import (
-            GenerationConfiguration,
-        )
-
-        _rel_schema_path = SCHEMA_DIR / schema_filename
-        _abs_schema_path = _rel_schema_path.absolute()
-        if not _abs_schema_path.exists():
-            msg = f"Schema doesn't exist at: {_abs_schema_path}"
-            raise FileNotFoundError(msg)
-
-        _config = GenerationConfiguration(
-            minify=False,
-            copy_css=False,
-            copy_js=False,
-            template_name="js",
-            expand_buttons=True,
-        )
-
-        content = generate_from_schema(_abs_schema_path, config=_config)
-
-        # get content ready for mkdocs
-        _footer = _get_html_between_tags(content, tag="footer")
-        replace_strings = {
-            "<!DOCTYPE html>": "",
-            '<div class="breadcrumbs"></div><span class="badge badge-dark value-type">\
-            Type: object</span><br/>': "",
-        }
-
-        for _orig, _new in replace_strings.items():
-            content = content.replace(_orig, _new)
-
-        content = _get_html_between_tags(content, tag="body")
-        content = _rm_html_between_tags(content, tag="footer")
-        return content
+    def document_schema(**kwargs) -> str:
+        """Generate Markdown documentation for a JSON schema."""
+        from projectcard.docs import json_schema_to_md
+
+        return json_schema_to_md(**kwargs)
 
     @env.macro
     def list_examples(data_dir: Path) -> str:

diff --git a/mkdocs.yml b/mkdocs.yml
@@ -15,8 +15,12 @@ theme:
   features:
     - content.code.annotate
     - content.code.copy
+    - content.tabs.link
+    - navigation.indexes
     - navigation.tabs
+    - navigation.expand
     - toc.integrate
+    - toc.follow
   palette:
     - scheme: default
       primary: blue grey
@@ -27,10 +31,12 @@ theme:
 plugins:
   - autorefs
   - awesome-pages
-  - include-markdown
-  - mike
+  - include-markdown:
+      opening_tag: "{!"
+      closing_tag: "!}"
   - macros
   - mermaid2
+  - mike
   - mkdocs-jupyter:
       include_source: True
   - mkdocstrings:
@@ -52,24 +58,24 @@ extra:
     default: latest
 
 extra_javascript:
-  - https://code.jquery.com/jquery-3.4.1.min.js
-  - https://stackpath.bootstrapcdn.com/bootstrap/4.3.1/js/bootstrap.min.js
+  - https://cdn.jsdelivr.net/npm/bootstrap@5.3.3/dist/js/bootstrap.min.js
   - javascript/schema_doc.min.js
 
 extra_css:
-
   - extra_css/extra.css
 
 markdown_extensions:
   - admonition
   - codehilite:
       linenums: true
   - meta
-  - pymdownx.inlinehilite
+  - pymdownx.details
   - pymdownx.highlight:
       anchor_linenums: true
       line_spans: __span
       pygments_lang_class: true
+      use_pygments: true
+  - pymdownx.inlinehilite
   - pymdownx.snippets
   - pymdownx.tasklist:
       custom_checkbox: true

diff --git a/projectcard/__init__.py b/projectcard/__init__.py
@@ -1,8 +1,9 @@
 """Project Card representation and validation."""
 
+from .errors import ProjectCardReadError, PycodeError, ValidationError
 from .io import read_card, read_cards, write_card
 from .logger import CardLogger, setup_logging
 from .projectcard import ProjectCard, SubProject
-from .validate import PycodeError, ValidationError, validate_card, validate_schema_file
+from .validate import validate_card, validate_schema_file
 
 __version__ = "0.3.0"