From 3d40f30a3cae0fdd390b13c89776f16057609f7c Mon Sep 17 00:00:00 2001 From: chrishavlin Date: Tue, 1 Aug 2023 14:08:00 -0500 Subject: [PATCH] update docs bit on keeping schema in sync --- README.md | 34 ++++++++++++++++++++++++++-------- 1 file changed, 26 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index 466b1e8..9b2a97f 100644 --- a/README.md +++ b/README.md @@ -176,20 +176,38 @@ This will update the `rst` files in `docs/source/` with the latest docstrings in ### updating the pydantic models and schema -Updates to the pydantic models should be accompanied by updates to the json schema. There are a number of utilities to help automate the management of schema. +The schema versioning follows a `major.minor.micro` versioning pattern that matches the yt-napari versioning. Each yt-napari release should have an accompanying updated schema file, even if the contents of the schema file have not changed. On-disk schema are stored in `src/yt_napari/schemas/`, with copies in the documentation at `docs/_static`. -The schema versioning follows a `major.minor.micro` versioning pattern and yt-napari schema are stored in `src/yt_napari/schemas/`. When changing the model, you can store a new schema from a python shell with: +There are a number of utilities to help automate the management of schema in `repo_utilities/`. The easiest way to use these utitities is with `taskipy` from the command line. To list available scripts: +```commandline +task --list +``` + +Before a release, run - from yt_napari._data_model import _store_schema - _store_schema() +```commandline +task validate_release vX.X.X +``` -And the current version of the primary pydantic model, `yt_napari._data_model.InputModel`, will be exported to a new json schema file. By default, the micro version number will be incremented. To increment the major or minor version number, you can supply any of the keyword arguments described in the `write_new_schema` method of the `yt_napari.schemas._mananager.Manager` class. +where `vX.X.X` is the version of the upcoming release. This script will run through some checks that ensure: +* the on-disk schema matches the schema generated by the pydantic model +* the schema files in the documentation match the schema files in the package -After updating or adding a new schema, the docs also need to be updated. To do that, run +If any of the checks fail, you will be advised to update the schema using `update_schema_docs`. If you +run without providing a version: - python repo_utilities/update_schema_docs.py - make clean && make html +```commandline +task update_schema_docs +``` + +It will simply copy over the existing on-disk schema files to the documentation. If you run with a version: + +```commandline +task update_schema_docs vX.X.X +``` +It will write a schema file for the current pydantic model, overwriting any on-disk schema files for +the provided version. ## License