Merge branch 'master' of github.com:ga4gh/refget

Author: nsheff

.readthedocs.yaml

@@ -1,11 +1,23 @@
 # Refget Docs
 
-This is the repository for documentation of the GA4GH Refget specifications, which includes both Refget Sequences and Refget Sequence Collections. These docs are written using `mkdocs` using Material for Mkdocs and hosted using GitHub Pages.
+This is the repository for documentation of the GA4GH Refget specifications, which includes both Refget Sequences and Refget Sequence Collections.
+These docs are written using `mkdocs`, themed with Material for Mkdocs, and hosted using GitHub Pages.
 
-## Building locally
+View the rendered documentation at <https://ga4gh.github.io/refget/>.
 
-Switch to the branch you want to build and use either `mkdocs build` or `mkdocs serve` to render the docs.
+## Navigating this repository
+
+The documentation is stored in the `/docs` folder, with a subfolder corresponding to each of the 3 refget standards.
+The main text content for each specifation can be found in these files:
+
+- Sequences: [/docs/sequences/README.md](/docs/sequences/README.md)
+- Sequence collections: [/docs/seqcols/README.md](/docs/seqcols/README.md)
+- Pangenomes: [/docs/pangenomes/README.md](/docs/pangenomes/README.md)
 
 ## Contributing
 
-Edit the files in the `docs` subdirectory. Please submit a PR to the appropriate branch for the version you are editing.
+To contribute, edit the files in the `docs` subdirectory. Please submit any changes for review via PR.
+
+## Building locally
+
+Switch to the branch you want to build and use either `mkdocs build` or `mkdocs serve` to render the docs.

README.md

@@ -1,8 +1,7 @@
-
-![GA4GH logo](img/ga4gh-logo.png){ width="300" align=right }
-
-
-# Refget specifications
+<div class="title container">
+<img src="img/ga4gh-logo.png" class="title" width="300">
+<h1>Refget specifications</h1>
+</div>
 
 ## What is refget?
 
@@ -12,9 +11,9 @@ It consists of these standards:
 
 | Standard      | Description                          | Status |
 | ----------- | ------------------------------------ | |
-| [Refget sequences](sequences.md)      | For individual sequences  | :white_check_mark: v1.0 Approved in 2021 <br>:white_check_mark:&nbsp;v2.0&nbsp;Approved in 2024 |
-| [Refget sequence collections](seqcol.md)      | For collections of sequences | :white_check_mark: v1.0 Approved in 2025 |
-| Refget pangenomes  | For collections of sequence collections | :fontawesome-solid-gears: Currently in process |
+| [Refget Sequences](sequences/README.md)      | For individual sequences  | :white_check_mark: v1.0 Approved in 2021 <br>:white_check_mark:&nbsp;v2.0&nbsp;Approved in 2024 |
+| [Refget Sequence Collections](seqcols/README.md)      | For collections of sequences | :white_check_mark: v1.0 Approved in 2025 |
+| Refget Pangenomes  | For collections of sequence collections | :fontawesome-solid-gears: Currently in process |
 
 
 ## What is the main purpose of the refget project?
@@ -26,7 +25,7 @@ Refget standards help to **identify**, **retrieve**, and **compare** reference s
 - Refget standards also specify **retrieval APIs**, providing a mechanism for retrieving a sequence or collection if you have its identifier.
 - Refget sequence collections also provides a programmatic approach to assessing compatibility among sequence collections.
 
-For more information about use cases, see the [use cases section of the sequence collections specification](seqcol.md#use-cases).
+For more information about use cases, see the [use cases section of the Sequence Collections specification](seqcols/README.md#use-cases).
 
 ## How do the standards work together?
 

docs/README.md

@@ -1,9 +1,17 @@
 # Citation information
 
+If you use any of the refget standards or software in your work, please cite us.
 
-Refget sequences was described in:
+## Refget sequences
 
-Yates AD; Adams J; Chaturvedi S; Davies RM; Laird M; Leinonen R; Nag R; Sheffield N.; Hofmann O & Keane TM.
+Please cite:
+
+Yates AD; Adams J; Chaturvedi S; Davies RM; Laird M; Leinonen R; Nag R; Sheffield NC; Hofmann O & Keane TM.
 **Refget: standardized access to reference sequences**. *Bioinformatics*, 2022, 38, 299-300. DOI: [10.1093/bioinformatics/btab524](https://dx.doi.org/10.1093/bioinformatics/btab524)
 
-Sequence collections has not been published.
+## Sequence collections
+
+Sequence collections publication is pending. An initial implementation that formed the groundwork for the current standard was described in:
+
+Stolarczyk M; Xue B; Sheffield NC.
+**Identity and compatibility of reference genome resources**. *NAR Genomics and Bioinformatics*, Volume 3, Issue 2, June 2021, lqab036. DOI: <https://doi.org/10.1093/nargab/lqab036>

docs/citation.md

@@ -414,15 +414,15 @@ Adding prefixes will complicate things and does not add benefits. Prefixes may b
 - <https://github.com/ga4gh/refget/issues/37>
 
 
-## 2023-06-28 - SeqCol JSON schema defines reserved attributes without additional namespacing
+## 2023-06-28 - Seqcol JSON schema defines reserved attributes without additional namespacing
 
 ### Decision
 
 One potential issue may arise if a custom implementation uses an attribute that a future version of seqcol adds to the schema, and if these attributes are defined differently. This will create a name clash and the custom implementation wouldn't be compatible with the future seqcol schema. It would be nice to prevent such future clashes, which would require ensuring that future seqcol attributes mean the same thing across collections so they are compatible. One way to solve this would be to define an namespace reserved by the specification, so that custom attributes look different and will therefore guarantee that custom attribute never clashes with seqcol attributes, thereby ensuring that custom implementations will be compatible with any future schema updates.
 
 Despite the potential issue for custom attribute clashes, we decided:
 
-1. We will not use any additional namespacing. Instead, the SeqCol schema declares and defines the specific attributes of a sequence collection. We will "claim" any reserved keywords in the secqol schema we publish, not by defining a style or namespace of reserved keywords.
+1. We will not use any additional namespacing. Instead, the seqcol schema declares and defines the specific attributes of a sequence collection. We will "claim" any reserved keywords in the secqol schema we publish, not by defining a style or namespace of reserved keywords.
 
 2. We will try to add to this many things that we forsee as possible attributes that could be defined in a seqcol. Thus, we will provide an official set of definitions that should prevent many possible future clashes.