Merge commit 'c5c8f9aeadd16a54bb6f0600395efc2c54f21cc3'

.github/workflows/ci.yaml

@@ -0,0 +1,33 @@
+name: CI
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+      with:
+        submodules: recursive
+
+    - name: Set up Python 3.12
+      uses: actions/setup-python@v5
+      with:
+        python-version: '3.12'
+        architecture: 'x64'
+
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install '.[dev]'
+
+    - name: Run lint + format
+      run: |
+        ruff check src
+
+    - name: Run tests
+      run: pytest

.gitignore

@@ -132,4 +132,5 @@ dmypy.json
 Pipfile*
 
 # IDEs
-.vscode
+.vscode
+.idea

Makefile

@@ -0,0 +1,40 @@
+PYV:=3.12
+VEDIR=venv/${PYV}
+
+############################################################################
+#= SETUP, INSTALLATION, PACKAGING
+
+#=> venv: make a Python 3 virtual environment
+.PHONY: venv/%
+venv/%:
+	python$* -m venv $@; \
+	source $@/bin/activate; \
+	python -m ensurepip --upgrade; \
+	pip install --upgrade pip setuptools
+
+#=> develop: install package in develop mode
+.PHONY: develop setup
+develop setup:
+	pip install -e '.[dev]'
+
+#=> devready: create venv, install prerequisites, install pkg in develop mode
+.PHONY: devready
+devready:
+	make ${VEDIR} && source ${VEDIR}/bin/activate && make develop
+	@echo '#################################################################################'
+	@echo '###  Do not forget to `source ${VEDIR}/bin/activate` to use this environment  ###'
+	@echo '#################################################################################'
+
+############################################################################
+#= TESTING
+# see test configuration in pyproject.toml
+
+#=> test: execute tests
+.PHONY: test
+test:
+	pytest tests/
+
+#=> doctest: execute documentation tests (requires extra data)
+.PHONY: doctest
+doctest:
+	pytest tests/ --doctest-modules

README.md

@@ -1,2 +1,115 @@
 # gks-metaschema
-Tools and scripts for parsing the GKS standards metaschemas
+
+
+Tools and scripts for parsing the GA4GH Genomic Knowledge Standards (GKS) metaschemas.
+The metaschema processor (MSP) converts
+[JSON Schema Version 2020-12](json-schema.org/draft/2020-12/schema) in YAML to
+reStructuredText (RST) and JSON files.
+
+Currently used in:
+
+* [GKS-Core](https://github.com/ga4gh/gks-core)
+* [VRS](https://github.com/ga4gh/vrs)
+* [VA-Spec](https://github.com/ga4gh/va-spec/)
+* [Cat-VRS](https://github.com/ga4gh/cat-vrs)
+
+## Installing for development
+
+### Prerequisites
+
+* Python 3.12: We recommend using [pyenv](https://github.com/pyenv/pyenv).
+
+### Installation Steps
+
+Fork the repo at <https://github.com/ga4gh/gks-metaschema>, and initialize a development
+environment.
+
+    git clone [email protected]:YOUR_GITHUB_ID/gks-metaschema.git
+    cd gks-metaschema
+    make devready
+    source venv/3.12/bin/activate
+
+
+Set up the `pre-commit` hook
+
+    cp ./scripts/pre-commit ./.git/hooks/
+
+
+### Testing
+
+To run the tests:
+
+    make test
+
+## Usage
+
+### File Hierarchy
+
+The metaschema processor expects the following hierarchy:
+
+    ├── docs
+    │   ├── source
+    │   |   ├── ...
+    │   ├── Makefile
+    ├── schema
+    │   ├──gks_schema
+    │   |   ├── gks-schema-source.yaml
+    │   |   ├── Makefile
+    │   |   ├── prune.mk
+    │   ├── Makefile
+
+* `docs`: [Sphinx](https://www.sphinx-doc.org/en/master/index.html) documentation
+    directory. **Must** be named `docs`.
+  * `source`: Directory containing documentation written in reStructuredText and Sphinx
+    configuration. **Must** be named `source`.
+  * `Makefile`: Commands to create the reStructuredText files.
+    This file should not change across GKS projects.
+* `schema`: Schema directory. Can also contain submodules for other GKS product schemas.
+  * `gks_schema`: Schema directory for GKS product. The directory name should reflect
+    the product, e.g. `vrs`.
+    * `gks-schema-source.yaml`: Source document for the JSON Schema 2020-12. The file name
+          should reflect the standard, e.g. `vrs-source.yaml`. The  file name **must** end
+          with `-source.yaml`.
+    * `Makefile`: Commands to create the reStructuredText and JSON files.
+          This file should not change across GKS projects.
+    * `prune.mk`: Cleanup of files in `def` and `json` directories based on source document.
+          This file should not change across GKS projects.
+  * `Makefile`: Commands to create the reStructuredText and JSON files.
+
+### Contributing to the schema
+
+To create the corresponding `def` (reStructuredText) and `json` files after making
+changes to the source document, from the _schema_ directory:
+
+        make all
+
+The file structure will now look like:
+
+    ├── schema
+    │   ├──gks_schema
+    |   |   ├── def
+    │   |   |   ├── ...
+    |   |   ├── json
+    │   |   |   ├── ...
+    │   |   ├── gks-schema-source.yaml
+    │   |   ├── Makefile
+    │   |   ├── prune.mk
+    │   ├── Makefile
+
+### Contributing to the docs
+
+GKS specification documentation is written in reStructuredText and located in
+`docs/source`.
+
+To build documentation locally, you must install [entr](https://eradman.com/entrproject/):
+
+    brew install entr
+
+Then from the _docs_ directory:
+
+    make clean watch &
+
+Then, open `docs/build/html/index.html`. The above make command should build docs when
+the source changes.
+
+> **NOTE**: Some types of changes require recleaning and building.

pyproject.toml

@@ -28,7 +28,17 @@ keywords = [
     "variation"
 ]
 requires-python = ">=3.12"
-dynamic = ["version", "dependencies"]
+dependencies = [
+    "pyyaml",
+    "Jinja2"
+]
+dynamic = ["version"]
+
+[project.optional-dependencies]
+dev = [
+    "pytest",
+    "ruff==0.7.2"
+]
 
 [project.urls]
 Homepage = "https://github.com/ga4gh/gks-metaschema"
@@ -37,9 +47,6 @@ Changelog = "https://github.com/ga4gh/gks-metaschema/releases"
 Source = "https://github.com/ga4gh/gks-metaschema"
 "Bug Tracker" = "https://github.com/ga4gh/gks-metaschema/issues"
 
-[tool.setuptools.dynamic]
-dependencies = {file = [".requirements.txt"]}
-
 [tool.setuptools_scm]
 
 [project.scripts]
@@ -53,3 +60,27 @@ source2classes = "ga4gh.gks.metaschema.scripts.source2classes:cli"
 [build-system]
 requires = ["setuptools>=65.3", "setuptools_scm>=8"]
 build-backend = "setuptools.build_meta"
+
+
+[tool.ruff]
+line-length = 120
+target-version = "py312"
+
+[tool.ruff.lint]
+select = [
+    "C",
+    "F",
+    "I",
+    "E",
+    "W"
+]
+fixable = ["ALL"]
+ignore = ["C901"]
+
+[tool.ruff.format]
+# Like Black, use double quotes for strings.
+quote-style = "double"
+# Like Black, indent with spaces, rather than tabs.
+indent-style = "space"
+# Like Black, respect magic trailing commas.
+skip-magic-trailing-comma = false

scripts/pre-commit

@@ -0,0 +1,16 @@
+#!/usr/bin/env bash
+# This pre-commit script should be placed in the .git/hooks/ directory.
+# It runs code quality checks prior to a commit.
+
+
+# Get and change to the root of the repo
+project_root_dir=`git rev-parse --show-toplevel`
+cd "$project_root_dir" || exit 1
+
+# Immediately exit if there's an error.
+set -e
+
+ruff check                   # Run the linter.
+ruff check --select I --fix  # Sort imports.
+ruff format                  # Run the formatter.
+pytest                       # Run the test suite.

src/ga4gh/gks/metaschema/scripts/jsy2js.py

@@ -1,12 +1,15 @@
 #!/usr/bin/env python3
 
-import yaml
 import json
 import sys
 
+import yaml
+
+
 def cli():
     yaml_schema = yaml.load(sys.stdin, Loader=yaml.SafeLoader)
     json.dump(yaml_schema, sys.stdout, indent=3)
 
+
 if __name__ == "__main__":
-    cli()
+    cli()

src/ga4gh/gks/metaschema/scripts/source2classes.py

@@ -1,8 +1,9 @@
 #!/usr/bin/env python3
 import argparse
-from ga4gh.gks.metaschema.tools.source_proc import YamlSchemaProcessor
 from pathlib import Path
 
+from ga4gh.gks.metaschema.tools.source_proc import YamlSchemaProcessor
+
 parser = argparse.ArgumentParser()
 parser.add_argument("infile")
 
@@ -13,10 +14,12 @@ def main(proc):
             continue
         print(cls)
 
+
 def cli():
     args = parser.parse_args()
     p = YamlSchemaProcessor(Path(args.infile))
     main(p)
 
-if __name__ == '__main__':
-    cli()
+
+if __name__ == "__main__":
+    cli()

src/ga4gh/gks/metaschema/scripts/source2jsy.py

@@ -2,12 +2,15 @@
 
 import pathlib
 import sys
+
 from ga4gh.gks.metaschema.tools.source_proc import YamlSchemaProcessor
 
+
 def cli():
     source_file = pathlib.Path(sys.argv[1])
     p = YamlSchemaProcessor(source_file)
     p.js_yaml_dump(sys.stdout)
 
+
 if __name__ == "__main__":
-    cli()
+    cli()

src/ga4gh/gks/metaschema/scripts/source2mergedjsy.py

@@ -2,13 +2,16 @@
 
 import pathlib
 import sys
+
 from ga4gh.gks.metaschema.tools.source_proc import YamlSchemaProcessor
 
+
 def cli():
     source_file = pathlib.Path(sys.argv[1])
     p = YamlSchemaProcessor(source_file)
     p.merge_imported()
     p.js_yaml_dump(sys.stdout)
 
+
 if __name__ == "__main__":
-    cli()
+    cli()