docs: update readme for installation + setup (#496)

korikuzma · jsstevenson · web-flow · commit 8e9596308d4a · 2024-05-17T15:55:36.000-04:00
docs: update readme for installation + setup
---------
Co-authored-by: James Stevenson &lt;james.sharpsteen@gmail.com&gt;
diff --git a/Makefile b/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 -r .requirements.txt
+
+#=> 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
diff --git a/README.md b/README.md
@@ -1,101 +1,89 @@
+# Variation Representation Specification (VRS)
+
 [![DOI](https://zenodo.org/badge/67005248.svg)](https://zenodo.org/badge/latestdoi/67005248)
 [![Read the Docs](https://img.shields.io/readthedocs/vr-spec/1.1)](https://vrs.ga4gh.org/)
 [![tests](https://github.com/ga4gh/vrs/actions/workflows/tests.yml/badge.svg)](https://github.com/ga4gh/vrs/actions/workflows/tests.yml)
 
-The [GA4GH](https://www.ga4gh.org/) [Variation Representation
-Specification](https://vrs.ga4gh.org/) provides a
-comprehensive framework for the computational representation of
-biological sequence variation.  VRS is the result of a
-collaboration among [contributors](CONTRIBUTORS.md) representing
-national information resource providers, major international public
-initiatives, and diagnostic testing laboratories.
+The [GA4GH](https://www.ga4gh.org/) [Variation Representation Specification](https://vrs.ga4gh.org/)
+provides a comprehensive framework for the computational representation of biological sequence
+variation. VRS is the result of a collaboration among [contributors](CONTRIBUTORS.md) representing
+national information resource providers, major international public initiatives, and diagnostic
+testing laboratories.
 
 VRS is licensed under the [Apache License 2.0](LICENSE).
 
+> **NOTE:** VRS is under active development.
+> See the [VRS Project Roadmap](https://github.com/orgs/ga4gh/projects/12).
 
-> **NOTE:** VRS is under active development.  See [VR
-> Project Roadmap](https://github.com/orgs/ga4gh/projects/5).
-
+## Specific goals
 
-# Specific goals:
-
-* Develop common language- and protocol-neutral information models and
-  nomenclature for biological sequence variation.
-* From the information models, develop data schemas.  The current
-  schema is defined in JSON Schema, but other formats are expected.
-* Provide algorithmic guidance and conventions to minimize
-  representational ambiguity.
-* Define a globally unique *computed identifier* for covered data
-  classes.
-* Develop [validation
-  tests](https://github.com/ga4gh/vrs/tree/main/validation) to ensure
+* Develop common language and protocol-neutral information models and nomenclature for
+  biological sequence variation.
+* From the information models, develop data schemas. The current schema is defined in
+  JSON Schema, but other formats are expected.
+* Provide algorithmic guidance and conventions to minimize representational ambiguity.
+* Define a globally unique *computed identifier* for covered data classes.
+* Develop [validation tests](https://github.com/ga4gh/vrs/tree/main/validation) to ensure
   consistency of implementations.
 
-The VRS model is the product of the [GA4GH Variation Representation
-group](https://ga4gh-gks.github.io/variant_representation.html).
-
-
-> **SEE ALSO**: See [vrs-python](https://github.com/ga4gh/vrs-python)
-> for an implementation and Jupyter notebooks.
-
-
-# Using the schema
+The VRS model is the product of the [GA4GH Variation Representation group](https://www.ga4gh.org/product/variation-representation/).
 
-The schema is available in the `schema/` directory, in both yaml and
-json versions.  It conforms to JSON Schema draft-07.  For a list of
-libraries that support JSON schema, see [JSON
-Schema>Implementations](https://json-schema.org/implementations.html).
+> **SEE ALSO**: See [VRS-Python](https://github.com/ga4gh/vrs-python) for a Python
+> implementation and Jupyter notebooks.
 
+## Using the schema
 
+The schema is available in the [schema/](./schema/) directory, in both yaml and json versions.
+It conforms to JSON Schema draft-07. For a list of libraries that support JSON schema,
+see [JSONSchema>Implementations](https://json-schema.org/implementations.html).
 
-# Contributing to the schema
+## Installing for development
 
-VRS uses yaml as the source document for JSON Schema
+Fork the repo at <https://github.com/ga4gh/vrs>.
 
-To convert vrs.yaml to vrs.json:
+    git clone --recurse-submodules git@github.com:YOUR_GITHUB_ID/vrs.git
+    cd vrs
+    make devready
+    source venv/3.12/bin/activate
 
-    make vrs.json
+If you already cloned the repo, but forgot to include `--recurse-submodules` you can run:
 
-You'll probably have to `pip install pyyaml` first.
+    git submodule update --init --recursive
 
-To watch for changes and update automatically:
+## Contributing to the schema
 
-    make -C schema watch &
+VRS uses [vrs-source.yaml](./schema//vrs/vrs-source.yaml) as the source document for JSON Schema.
 
+To create the corresponding def and json files after making changes to the source document, from the root directory:
 
-# Contributing docs
+    cd schema
+    make all
 
-The VR specification documentation is written in reStructuredText and
-located in `docs/source/`.  Commits to this repo are built
-automatically at `vrs.ga4gh.org`.
+## Contributing to the docs
 
-To build documentation locally, type:
+The VRS specification documentation is written in reStructuredText and located in [docs/source](docs/source/). Commits to this repo are built automatically at <https://vrs.ga4gh.org>.
 
-    make -C docs clean watch &
+To build documentation locally, you must install `entr`:
 
-Then, open `docs/build/html/index.html`.  The above make command
-should build docs when source changes. (Some types of changes require
-recleaning and building.)
+    brew install entr
 
+Then from the root directory:
 
-# Testing
+    cd docs
+    make clean watch &
 
-The VRS repo contains two kinds of tests. Basic smoketests in `tests/`
-ensure that the schema is parseable and works with certain tools.
-These tests provide a basic sanity check during development.
+Then, open `docs/build/html/index.html`. The above make command should build docs when
+source changes. (Some types of changes require recleaning and building.)
 
-Validation tests (in `validation/`) provide language-neutral tests for
-those implementing tools with VRS.
+## Testing
 
-## Using smoketests
+The VRS repo contains two kinds of tests. Basic smoke tests in `tests/` ensure that the
+schema is parsable and works with certain tools. These tests provide a basic sanity
+check during development.
 
-The smoketests require python 3.8+. This is the recommended setup:
+Validation tests (in `validation/`) provide language-neutral tests for those implementing
+tools with VRS.
 
-```
-$ python3 -m venv venv
-$ source venv/bin/activate
-$ pip install -U setuptools pip
-$ pip install -r .requirements.txt
-$ python3 -m pytest
+To run the smoke tests:
 
-```
+    make test
