Merge pull request #2317 from microbiomedata/doc_updates_2025

Doc updates 2025

Makefile

@@ -173,12 +173,11 @@ $(DOCDIR):
 gendoc: $(DOCDIR) prefixmaps
 	# Copy all documentation files to the documentation directory
 	cp -rf $(SRC)/docs/* $(DOCDIR)
-	# Added copying of images and renaming of TEMP.md
-	cp $(SRC)/docs/*md $(DOCDIR)
-	cp -r $(SRC)/docs/images $(DOCDIR)
 	# Generate documentation using the gen-doc command
 	$(RUN) gen-doc -d $(DOCDIR) --template-directory $(SRC)/$(TEMPLATEDIR) --include src/schema/deprecated.yaml $(SOURCE_SCHEMA_PATH)
 	# Create directory for JavaScript files and copy them
+	# Added copying of prefixmaps output
+	cp -f $(DEST)/prefixmap/nmdc-prefix-map.json $(DOCDIR)
 	mkdir -p $(DOCDIR)/javascripts
 	$(RUN) cp $(SRC)/scripts/*.js $(DOCDIR)/javascripts/
 	# Use `refgraph` to generate an interactive diagram within the compiled documentation website file tree.

mkdocs.yml

@@ -6,6 +6,10 @@ theme:
   #    primary: cyan
   features:
     - content.tabs.link
+    - hide_page_title
+  logo: images/NMDC_logo.png
+extra:
+  favicon: images/favicon.ico
 plugins:
   - search
   - mermaid2:
@@ -22,19 +26,18 @@ extra_javascript:
   - javascripts/tablesort.js
 nav:
   # Reference: https://www.mkdocs.org/user-guide/configuration/#nav
-  - NMDC Schema: index.md
-  - About: about.md
-  - How to run a collaborative data modeling project: https://linkml.io/linkml/howtos/collaborative-development.html
-  - Identifiers in NMDC: identifiers.md
-  - Identifiers, CURIes, Prefixes, etc.: prefixes_curies_ids_mappings_etc.md
-  - NMDC Metadata Standards Documentation: Metadata_Documentation_Overview.md
-  - NMDC Schema Contributors How-to from Schema Hackathon 2023-12-10: https://docs.google.com/presentation/d/1ZH41QAoESUwAkdHyUxlrmSKS5M-bT0TOulBgX4rBx2A/edit#slide=id.g26390794265_0_693
-  - NMDC Schema Validation: schema-validation.md
+  - Overview: index.md
+  - Funding and Acknowledgements: about.md
+  - Contributing: collaboration.md
+  - Metadata Standards Documentation: Metadata_Documentation_Overview.md
+  - Maintaining the NMDC Schema: maintaining-the-schema.md
   - Schema element deprecation guide: schema_element_deprecation_guide.md
-  - v10 vs v11 (Berkeley schema) retrospective: v10-vs-v11-retrospective.md
+  - NMDC Schema Validation: schema-validation.md
+  - Identifiers: identifiers.md
+  - Version Migration Guides: migrations.md
   - Visualizations: visualizations.md
   - Data Validation: validation.md
-  - SchemaView: schemaview.md
+  - Developer Docs: developer-docs.md
 
 
 site_url: https://microbiomedata.github.io/nmdc-schema

src/doc-templates/index.md.jinja2

@@ -1,7 +1,17 @@
-# {{ schema.name }}
+# National Microbiome Data Collaborative Schema Documentation
+![NMDC_logo.png](images/NMDC_logo.png)
 
 {{ schema.description }}
 
+This schema is organized into two modules:
+
+* A core set of elements for representing data values represented in LinkML format (https://w3id.org/linkml/) consisting
+of a set classes, slots, types, and enumerations that are used to define the structure of the NMDC schema.
+
+* A subset of the MIxS schema developed by the Genomic Standards Consortium, that is used to describe the
+environmental context of samples.
+
+
 URI: <a href={{ schema.id }}>{{ schema.id }}</a>
 
 

src/docs/Metadata_Documentation_Overview.md

@@ -1,5 +1,4 @@
 # The NMDC Metadata Standards Documentation
-# Introduction
 
 This documentation provides details on the National Microbiome Data
 Collaborative’s ([<u>NMDC</u>](http://microbiomedata.org)) approach to
@@ -67,7 +66,7 @@ environment, elevation, altitude, depth, etc.) organized into different
 packages for 17 different sample environments.
 
 To standardize how physical samples are described (i.e., sample
-metadata, Figure 1), the NMDC schema includes environmental descriptors
+metadata, Figure 1), the NMDC Schema includes environmental descriptors
 from the GSC MIxS standards.
 
 *Explore how to create a MIxS-compliant sample metadata spreadsheet*
@@ -279,7 +278,7 @@ relationships between samples, and associated data objects. The schema
 is organized into object classes, which act as nodes. Each class has
 associated slots, which are fields that contain metadata that describe
 the object. For more in-depth information, full documentation of the
-NMDC schema can be found
+NMDC Schema can be found
 [<u>here</u>](https://microbiomedata.github.io/nmdc-metadata/#classes).
 
 For the NMDC pilot, a python

src/docs/about.md

@@ -1,11 +1,30 @@
-## NMDC Schema
+# Funding and Acknowledgements
 
-**Schema resources for the National Microbiome Data Collaborative (NMDC)**
+The work conducted by the National Microbiome Data Collaborative (https://ror.org/05cwx3318) is supported by the 
+Genomic Science Program in the U.S. Department of Energy, Office of Science, Office of Biological and Environmental 
+Research (BER) under contract numbers DE-AC02-05CH11231 (LBNL), 89233218CNA000001 (LANL), and DE-AC05-76RL01830 (PNNL).
 
-The purpose of the NMDC Schema is to define metadata for the [National Microbiome Data Collaborative (NMDC)](https://microbiomedata.org/). The [NMDC](https://microbiomedata.org/) is a multi-organizational effort to enable integrated microbiome data across diverse areas in medicine, agriculture, bioenergy, and the environment. This integrated platform facilitates comprehensive discovery of and access to multidisciplinary microbiome data in order to unlock new possibilities with microbiome data science. 
+![DOE_logo.png](images/DOE_logo.png)
 
-The NMDC schema is used during the translation process to specify how metadata elements are related.
+## Framework
 
-## Credits
+This schema was made using the [LinkML framework](https://linkml.github.io/linkml). LinkML is a data modeling language 
+that is used to create data models in a human-readable format. The LinkML framework is used to generate 
+the schema in multiple formats, including JSON-LD, YAML, and RDF.
 
-this project was made using the [LinkML framework](https://github.com/biolink/biolinkml)
+NMDC uses the LinkML framework to create a schema to be used by researchers, data scientists, and developers to 
+understand the structure of the data and how it is related.
+
+## Citing NMDC
+
+### Schema
+
+Microbiome Data Coordination Center. (n.d.). NMDC Schema. GitHub. from https://github.com/microbiomedata/nmdc-schema
+
+### Program Launch
+E. M. Wood-Charlson, Anubhav, D. Auberry, H. Blanco, M. I. Borkum, Y. E. Corilo, K. W. Davenport, S. Deshpande, 
+R. Devarakonda, M. Drake, W. D. Duncan, M. C. Flynn, D. Hays, B. Hu, M. Huntemann, P.-E. Li, M. Lipton, C.-C. Lo, 
+D. Millard, K. Miller, P. D. Piehowski, S. Purvine, T. B. K. Reddy, M. Shakya, J. C. Sundaramurthi, P. Vangay, Y. Wei, 
+B. E. Wilson, S. Canon, P. S. G. Chain, K. Fagnan, S. Martin, L. A. McCue, C. J. Mungall, N. J. Mouncey, M. E. Maxon, 
+E. A. Eloe-Fadrosh, The National Microbiome Data Collaborative: enabling microbiome science. Nature Reviews 
+Microbiology 18, 313-314 (2020). doi: 10.1038/s41579-020-0377-0

src/docs/collaboration.md

@@ -0,0 +1,33 @@
+# Collaborating on NMDC Schema
+
+NMDC Schema is a collaborative, multidisciplinary project that seeks to harmonize data across the microbiome research
+community.  We welcome any and all kinds of contributions. Our goal is to make it easy for you to contribute to the 
+project, and to make sure that your contributions are properly reviewed and integrated.
+
+## How can I contribute?
+
+We welcome any and all kinds of contribution, including:
+
+ * bug fixes and code contributions
+ * ideas for new features
+ * testing
+ * documentation improvements
+ * stylistic improvements
+ * general suggestions on how we can do better
+
+Please see our [Contributing Guidelines](https://github.com/microbiomedata/nmdc-schema/blob/main/CONTRIBUTING.md) for 
+more information on how to contribute to the project, and 
+our [Code of Conduct](https://github.com/microbiomedata/nmdc-schema/blob/main/CODE_OF_CONDUCT.md) for information on
+how to interact with the community.
+
+## How do I do X? Why doesn’t Y work? Where can I go to get help?
+
+First, please check if your question is answered on the FAQ and or in this documentation.
+We always welcome questions, bug reports, feature requests, and feedback via our GitHub issue tracker:
+
+[https://github.com/microbiomedata/nmdc-schema/issues](https://github.com/microbiomedata/nmdc-schema/issues)
+
+## How do I run a collaborative schema project?
+
+Please check some guidelines from LinkML Schema Developers: [https://linkml.io/linkml/howtos/collaborative-development.html](https://linkml.io/linkml/howtos/collaborative-development.html)
+Consult NMDC Schema Contribution guidelines directly: [GoogleSlides](https://docs.google.com/presentation/d/1ZH41QAoESUwAkdHyUxlrmSKS5M-bT0TOulBgX4rBx2A/edit#slide=id.g26390794265_0_693)

src/docs/developer-docs.md

@@ -0,0 +1,17 @@
+# Schema Developer FAQs
+
+Some frequently asked questions about developing the NMDC Schema.
+
+### What are some effective strategies for collaborative schema development?
+
+[LinkML Collaborative Development](https://linkml.io/linkml/howtos/collaborative-development.html)
+[Google Slides Presentation](https://docs.google.com/presentation/d/1ZH41QAoESUwAkdHyUxlrmSKS5M-bT0TOulBgX4rBx2A/edit#slide=id.g26390794265_0_693)
+
+### How do I migrate from one version of the NMDC schema to another?
+
+[Version 10 to 11 migration](v10-vs-v11-retrospective.md)
+
+### How do I view the NMDC schema programmatically?
+
+[NMDC SchemaView Documentation](schemaview.md)
+[SchemaView Documentation](https://linkml.github.io/linkml/schemaview.html)