docs: fix a bunch of things

.gitignore

@@ -134,3 +134,6 @@ dmypy.json
 
 # Pipfile
 Pipfile*
+
+# MacOS things
+.DS_Store

docs/source/appendices/design-decisions.rst

@@ -29,7 +29,7 @@ reporting **case-level observations** about a variant to other standards (e.g. P
 Explicit Statement Semantics
 ############################
 
-In the VA data, each assertion of knowledge about a variant is captured in a self-contained ``Statement`` object. Statements put forth a Proposition that expresses some possible fact about the world, and may provide an assessment of this proposition's validity (i.e. how likely it is to be true or false based on evaluated evidence). The semantics of this possible fact are captured in a ``Proposition`` object, using ``subject``, ``predicate``, ``object``, and optional ``qualifier`` attributes (**SPOQ**). An assessment of the Proposition's  validity can optionally be captured using ``direction``, ``strength``, and/or ``score`` attributes (**DS**).  See `here <https://va-ga4gh.readthedocs.io/en/latest/core-information-model/entities/information-entities/statement.html>`_ for more.
+In the VA data, each assertion of knowledge about a variant is captured in a self-contained ``Statement`` object. Statements put forth a Proposition that expresses some possible fact about the world, and may provide an assessment of this proposition's validity (i.e. how likely it is to be true or false based on evaluated evidence). The semantics of this possible fact are captured in a ``Proposition`` object, using ``subject``, ``predicate``, ``object``, and optional ``qualifier`` attributes (**SPOQ**). An assessment of the Proposition's  validity can optionally be captured using ``direction``, ``strength``, and/or ``score`` attributes (**DS**).  See :ref:`here <Statement>` for more.
 
 Organization of variant knowledge into discrete Statement objects allows clear and precise tracking of the evidence and provenance that supports each. And as modular, self-contained structures, they can be re-used in different contexts in an annotation - as the primary statement being made, or a piece of evidence supporting such a statement. Finally, the consistent structured representation of semantics across all Statement types provides a framework for human and computational agents to identify what is being asserted as true, and what is accessory or supporting information.
 
@@ -54,8 +54,9 @@ The VA-Spec does not define detailed models for representing such domain entitie
 
 Where suitable standards exist they are incorporated into the VA-Spec - as we have done with the `VRS <https://vrs.ga4gh.org/en/latest/index.html>`_ and `CatVRS <https://cat-vrs.readthedocs.io/en/latest/index.html>`_ models for representing genetic variation.
 
-Version 1 of the VA-Spec represents all other Domain Entity types using a simple :ref:`IRI Reference <iriReference>`, or a :ref:`Mappable Concept <mappable-concept>` which bundles an established code for the entity with metadata and mappings for the code and code system. Where there is a need to represent collections of more than one Domain Entity, classes are defined to capture these as sets of Mappable Concepts (e.g. ``ConditionSet``, ``Therapy Group``). More information and examples of Domain Entity representation can be found `here <https://va-ga4gh.readthedocs.io/en/latest/core-information-model/domain-entities.html>`_.
+Version 1 of the VA-Spec represents all other Domain Entity types using a simple :ref:`IRI Reference <iriReference>`, or a :ref:`Mappable Concept <mappable-concept>` which bundles an established code for the entity with metadata and mappings for the code and code system. Where there is a need to represent collections of more than one Domain Entity, classes are defined to capture these as sets of Mappable Concepts (e.g. ``ConditionSet``, ``Therapy Group``). More information and examples of Domain Entity representation can be found :ref:`here <domain-entities>`.
 
+.. _profile-authoring-mechanisms:
 
 Profile Authoring Mechanisms
 ############################

docs/source/appendices/implementations.rst

@@ -20,7 +20,7 @@ of the VA-Spec. They are expected to be updated as the VA-Spec is finalized.
       - `GA4GH VA-Spec Python Repository <https://github.com/ga4gh/va-spec-python>`_
       - The reference implementation for VA-Spec, this python package provides tools for generation and validation of VA-Spec objects.
    *  - VICC MetaKB
-      - `Cancer Variants API v2 (Dev) <https://dev-search.cancervariants.org/api/v2>`_
+      - `Online MetaKB UI <https://pediatric.metakb.org/>`_
       - The VICC Meta-Knowledgebase (MetaKB) v2 is currently under development as a knowledge integration engine that works across germline and somatic variant evidence. It represents genomic knowledge statements using the VA-Spec v1.0 March pre-release.
    *  - ClinVar Submission Utility
       - `ClinVar This Repository <https://github.com/clingen-data-model/clinvar-this>`_

docs/source/appendices/imported-models/allele.rst

@@ -0,0 +1,6 @@
+.. _Allele:
+
+Allele
+!!!!!!
+
+.. include::  ../../def/vrs/Allele.rst

docs/source/appendices/imported-models/categorical-variant.rst

@@ -0,0 +1,6 @@
+.. _CategoricalVariant:
+
+CategoricalVariant
+!!!!!!!!!!!!!!!!!!
+
+.. include::  ../../def/cat-vrs/CategoricalVariant.rst

docs/source/appendices/imported-models/constraint.rst

@@ -0,0 +1,6 @@
+.. _Constraint:
+
+Constraint
+!!!!!!!!!!
+
+.. include::  ../../def/cat-vrs/Constraint.rst

docs/source/appendices/imported-models/expression.rst

@@ -0,0 +1,6 @@
+.. _Expression:
+
+Expression
+!!!!!!!!!!
+
+.. include::  ../../def/vrs/Expression.rst

docs/source/appendices/imported-models/ga4gh-identifiable-object.rst

@@ -0,0 +1,6 @@
+.. _Ga4ghIdentifiableObject:
+
+Ga4ghIdentifiableObject
+!!!!!!!!!!!!!!!!!!!!!!!
+
+.. include::  ../../def/vrs/Ga4ghIdentifiableObject.rst

docs/source/appendices/imported-models/index.rst

@@ -0,0 +1,32 @@
+Imported Data Types & Classes
+!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+VA-Spec makes use of a number of types and classes maintained by other GKS groups. This section includes descriptions and references for those models beyond what is provided in :ref:`va-core-model` for completeness.
+
+
+VRS
+###
+.. toctree::
+   :titlesonly:
+
+   ga4gh-identifiable-object
+   sequence-string
+   residue
+   molecular-variation
+   allele
+   location
+   sequence-location
+   sequence-reference
+   expression
+   sequence-expression
+   range
+
+
+Cat-VRS
+#######
+
+.. toctree::
+   :titlesonly:
+
+   categorical-variant
+   constraint

docs/source/appendices/imported-models/location.rst

@@ -0,0 +1,6 @@
+.. _Location:
+
+Location
+!!!!!!!!
+
+.. include::  ../../def/vrs/Location.rst

docs/source/appendices/imported-models/molecular-variation.rst

@@ -0,0 +1,6 @@
+.. _MolecularVariation:
+
+MolecularVariation
+!!!!!!!!!!!!!!!!!!
+
+.. include::  ../../def/vrs/MolecularVariation.rst

docs/source/appendices/imported-models/range.rst

@@ -0,0 +1,6 @@
+.. _Range:
+
+Range
+!!!!!!!!!!
+
+.. include::  ../../def/vrs/Range.rst

docs/source/appendices/imported-models/residue.rst

@@ -0,0 +1,6 @@
+.. _Residue:
+
+Residue
+!!!!!!!
+
+.. include::  ../../def/vrs/Residue.rst

docs/source/appendices/imported-models/sequence-expression.rst

@@ -0,0 +1,6 @@
+.. _SequenceExpression:
+
+SequenceExpression
+!!!!!!!!!!!!!!!!!!
+
+.. include::  ../../def/vrs/SequenceExpression.rst

docs/source/appendices/imported-models/sequence-location.rst

@@ -0,0 +1,6 @@
+.. _SequenceLocation:
+
+SequenceLocation
+!!!!!!!!!!!!!!!!
+
+.. include::  ../../def/vrs/SequenceLocation.rst

docs/source/appendices/imported-models/sequence-reference.rst

@@ -0,0 +1,6 @@
+.. _SequenceReference:
+
+SequenceReference
+!!!!!!!!!!!!!!!!!!
+
+.. include::  ../../def/vrs/SequenceReference.rst

docs/source/appendices/imported-models/sequence-string.rst

@@ -0,0 +1,6 @@
+.. _sequenceString:
+
+sequenceString
+!!!!!!!!!!!!!!
+
+.. include::  ../../def/vrs/sequenceString.rst

docs/source/appendices/index.rst

@@ -14,3 +14,4 @@ Appendices
    implementations
    variant-congruence
    maturity_model
+   imported-models/index

docs/source/appendices/maturity_model.rst

@@ -0,0 +1,3 @@
+.. _gks-maturity-model:
+
+.. include:: ../../../submodules/cat-vrs/submodules/vrs/docs/source/appendices/maturity_model.rst

docs/source/appendices/variant-congruence.rst

@@ -1,4 +1,4 @@
-.. _variant-congruence
+.. _variant-congruence:
 
 Variant Congruence
 !!!!!!!!!!!!!!!!!!
@@ -7,6 +7,6 @@ This concerns the notion that the variant subject of a Statement's Proposition m
 
 For example, Pathogenicity Statements often report knowledge about a `Categorical Variant <https://cat-vrs.readthedocs.io/en/latest/introduction.html>`_ such as *BRAF V600E*, while an Experimental Functional Impact Study Result supporting it may describe a discrete **protein-level variant** such as *NP_004324.2:p.Val600Glu*, and a Cohort Allele Frequency Study Result supporting it may describe a discrete **genomic-level variant** such as *NC_000007.13:g.140453136A>T* - both of which are covered by the definition of the *BRAF V600E* Categorical Variant.
 
-The computational foundations of the `VRS <https://github.com/ga4gh/vrs>`_ and `CatVRS <https://github.com/ga4gh/cat-vrs>`_ specifications are designed to enable mappings between discrete variants defined on different references contexts or molecule types, and mappings from discrete variation to broader Categorical Variant concepts to which they 'belong'. This is essential for aggregating evidence attached to related variation defined at different levels of specificity - as illustrated in :ref:`this scenario <acmg-variant-pathogenicity-statement-example-with-evidence>` where data about the frequency of discrete alleles defined in a genomic context, and functional data about discrete variants defined in a protein context, are assembled and interpreted as evidence for the pathogenicity classification of a broader categorical variation.
+The computational foundations of the `VRS <https://vrs.ga4gh.org/>`_ and `CatVRS <https://cat-vrs.ga4gh.org/>`_ specifications are designed to enable mappings between discrete variants defined on different references contexts or molecule types, and mappings from discrete variation to broader Categorical Variant concepts to which they 'belong'. This is essential for aggregating evidence attached to related variation defined at different levels of specificity - as illustrated in :ref:`this scenario <acmg-variant-pathogenicity-statement-example-with-evidence>` where data about the frequency of discrete alleles defined in a genomic context, and functional data about discrete variants defined in a protein context, are assembled and interpreted as evidence for the pathogenicity classification of a broader categorical variation.
 
-For more on this challenge and solutions, explore the `VRS <https://vrs.ga4gh.org/en/stable/introduction.html>`_ and `Cat-VRS <https://cat-vrs.readthedocs.io/en/latest/introduction.html>`_ documentation.
+For more on this challenge and solutions, explore the `VRS <https://vrs.ga4gh.org/>`_ and `Cat-VRS <https://cat-vrs.ga4gh.org>`_ documentation.

docs/source/conf.py

@@ -9,6 +9,7 @@
 import requests
 import subprocess
 
+
 def get_rtd_branch_from_github(repo="ga4gh/va-spec", default="main"):
     """
     If on ReadTheDocs and building a PR, fetch the true source branch name from GitHub.
@@ -19,7 +20,7 @@ def get_rtd_branch_from_github(repo="ga4gh/va-spec", default="main"):
             result = subprocess.run(
                 ["git", "rev-parse", "--abbrev-ref", "HEAD"],
                 capture_output=True,
-                check=True
+                check=True,
             )
             branch = result.stdout.decode().strip()
             return branch if branch != "HEAD" else default
@@ -39,7 +40,7 @@ def get_rtd_branch_from_github(repo="ga4gh/va-spec", default="main"):
         response = requests.get(
             f"https://api.github.com/repos/{repo}/pulls/{pr_number}",
             headers=headers,
-            timeout=5
+            timeout=5,
         )
         if response.status_code == 200:
             return response.json()["head"]["ref"]  # actual source branch name
@@ -50,6 +51,7 @@ def get_rtd_branch_from_github(repo="ga4gh/va-spec", default="main"):
 
     return f"pull/{pr_number}"
 
+
 # def get_git_branch_or_default(default="main"):
 #     """
 #     Get the current git branch even in a ReadTheDocs detached state.
@@ -74,6 +76,7 @@ def get_rtd_branch_from_github(repo="ga4gh/va-spec", default="main"):
 #     except subprocess.CalledProcessError:
 #         return default
 
+
 def get_exact_git_tag():
     """
     Returns the exact tag for the current Git commit, if one exists.
@@ -83,7 +86,7 @@ def get_exact_git_tag():
         result = subprocess.run(
             ["git", "describe", "--tags", "--exact-match"],
             capture_output=True,
-            check=True
+            check=True,
         )
         tag = result.stdout.decode().strip()
         return tag if tag else None
@@ -94,24 +97,27 @@ def get_exact_git_tag():
 # -- Project information -----------------------------------------------------
 
 print("*!*!*!*!* Branch detected:", get_rtd_branch_from_github())
-print("RTD env:", {
-    "READTHEDOCS": os.environ.get("READTHEDOCS"),
-    "READTHEDOCS_VERSION": os.environ.get("READTHEDOCS_VERSION"),
-    "READTHEDOCS_VERSION_TYPE": os.environ.get("READTHEDOCS_VERSION_TYPE"),
-})
-
-project = 'GA4GH Variant Annotation Specification'
-copyright = '2024, GA4GH VA Contributors'
-author = 'Committers'
-master_doc = 'index'
+print(
+    "RTD env:",
+    {
+        "READTHEDOCS": os.environ.get("READTHEDOCS"),
+        "READTHEDOCS_VERSION": os.environ.get("READTHEDOCS_VERSION"),
+        "READTHEDOCS_VERSION_TYPE": os.environ.get("READTHEDOCS_VERSION_TYPE"),
+    },
+)
+
+project = "GA4GH Variant Annotation Specification"
+copyright = "2024, GA4GH VA Contributors"
+author = "Committers"
+master_doc = "index"
 # get the release from the git tag if available, otherwise use the branch name
 release = get_exact_git_tag()
 if release == None:
     # If not on a tagged release, use the branch name
     release = get_rtd_branch_from_github(default="1.0")
 
 # Load static rst_epilog from file
-rst_epilog_fn = os.path.join(os.path.dirname(__file__), 'rst_epilog')
+rst_epilog_fn = os.path.join(os.path.dirname(__file__), "rst_epilog")
 with open(rst_epilog_fn, encoding="utf-8") as f:
     static_epilog = f.read().format(release=release)
 
@@ -137,32 +143,33 @@ def get_exact_git_tag():
         if "=" in line:
             label, filepath = [part.strip() for part in line.split("=", 1)]
             url = f"{github_base}/{filepath}"
-            label_text = label.replace('_', ' ').title()
+            label_text = label.replace("_", " ").title()
             link = f".. |{label}| replace:: `{label_text} <{url}>`__"
             dynamic_links.append(link)
 
 # Combine everything into dynamic_epilog
 dynamic_epilog = "\n".join(dynamic_links)
 
 # Combine both static and dynamic epilogs
-rst_epilog = static_epilog  + "\n" + dynamic_epilog
+rst_epilog = static_epilog + dynamic_epilog
 
 # -- General configuration ---------------------------------------------------
 
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
-    'sphinx.ext.todo'
+    "sphinx.ext.todo",
+    "sphinx.ext.extlinks",
 ]
 
 # Add any paths that contain templates here, relative to this directory.
-templates_path = ['_templates']
+templates_path = ["_templates"]
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This pattern also affects html_static_path and html_extra_path.
-exclude_patterns = []
+exclude_patterns = ["def/**"]
 
 # TODO directive output
 todo_include_todos = True
@@ -173,28 +180,41 @@ def get_exact_git_tag():
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = 'sphinx_rtd_theme'
+html_theme = "sphinx_rtd_theme"
 html_theme_options = {
-    'navigation_depth': 5,  # Increase to 4 levels of nested sections
-    'collapse_navigation': False
+    "navigation_depth": 5,  # Increase to 4 levels of nested sections
+    "collapse_navigation": False,
 }
-html_logo = 'images/GA-logo.png'
+html_logo = "images/GA-logo.png"
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['_static']
+html_static_path = ["_static"]
 
-html_css_files = ['theme_overrides.css']
+html_css_files = ["theme_overrides.css"]
 
 # Sidebars
 
-html_sidebars = { '**': ['globaltoc.html', 'relations.html',
-                         'sourcelink.html', 'searchbox.html'] }
+html_sidebars = {
+    "**": ["globaltoc.html", "relations.html", "sourcelink.html", "searchbox.html"]
+}
 html_context = {
     "conf_py_path": "/docs/source/",
     "display_github": True,
     "github_user": "ga4gh",
     "github_repo": "va-spec",
     "github_version": release,
 }
+
+# -- extlinks ----------------------------------------------------------------
+
+# use the `extlinks` extension to configure external links to resources like GitHub,
+# where a prefix might be used to dictate branch/version/etc
+# much of what lies in `github_links.txt`, along with the "dynamic epilog" above,
+# could probably be refactored to this
+
+extlinks = {
+    "gks_core_source": ("https://github.com/ga4gh/gks-core/blob/v1/%s", None),
+    "cat_vrs_source": ("https://github.com/ga4gh/cat-vrs/blob/v1/%s", None),
+}

docs/source/core-information-model/domain-entities.rst

@@ -63,7 +63,7 @@ To represent these diverse types of variation, the VA-Spec imports two complemen
 
 **Examples**
   - A |discrete_allele| as a VRS object
-  - A |canonical_allele| as a Cat-VRS object
+  - A :cat_vrs_source:`Canonical Allele<examples/canonicalAllele-ex1.yaml>` as a Cat-VRS object
 
 .. _Condition:
 
@@ -151,10 +151,10 @@ A gene is a region (or regions) of genetic sequence that includes all of the ele
 
 **Information Model**
 
-No dedicated class or schema is defined for Genes at present. Rather, individual genes are referenced in data using an :ref:`IRI Reference <iriReference> or a :ref:`Mappable Concept <mappable-concept>` that captures a code or name for the gene, along with optional mappings and metadata about the code system
+No dedicated class or schema is defined for Genes at present. Rather, individual genes are referenced in data using an :ref:`IRI Reference <iriReference>` or a :ref:`Mappable Concept <mappable-concept>` that captures a code or name for the gene, along with optional mappings and metadata about the code system
 
 **Examples**
-  - |brca2_gene| as a Mappable Concept
+  - :gks_core_source:`BRCA2 <examples/mappable-concept-gene.yaml>` as a MappableConcept
 
 
 -----------

docs/source/core-information-model/elements/concept-mapping.rst

@@ -11,6 +11,7 @@ Concept Mapping
 **IMPLEMENTATION GUIDANCE**
 
 1. Populating the ``relation`` attribute
+
  - A mapping relation must be provided in any ConceptMapping.
  - Permissible values come from the 'mapping relation' branch of the `Simple Knowledge Organization System (SKOS) <https://www.w3.org/2004/02/skos/>`_, which includes 5 possible mapping relations: