metamodel docs (#133)

* Adding metamodel docs

* Adding docs target.

Sphinx update

* docs-target

Author: cmungall

.github/workflows/doc_pages.yaml

@@ -27,6 +27,7 @@ jobs:
       run: |
         mkdir gh-pages
         touch gh-pages/.nojekyll
+        make all-docs
         cd docs/
         poetry run sphinx-build -b html . _build
         cp -r _build/* ../gh-pages/
@@ -37,4 +38,4 @@ jobs:
       with:
         branch: gh-pages
         force: true
-        folder: gh-pages
+        folder: gh-pages

Makefile

@@ -1,76 +1,39 @@
 RUN = poetry run
 VERSION = $(shell git tag | tail -1)
+MODELS = cadsr frictionless
 
-.PHONY: all clean test
+.PHONY: all clean test all-docs sphinx-html
 
-all: clean test target/soil_meanings.yaml
+all: clean test
 
 
-clean:
-	rm -rf target/soil_meanings.yaml
-	rm -rf target/soil_meanings_generated.yaml
-	rm -rf target/availabilities_g_s_strain_202112151116.yaml
-	rm -rf target/availabilities_g_s_strain_202112151116_org_meanings.yaml
-
 test:
 	$(RUN) pytest tests/
 
 schema_automator/metamodels/%.py: schema_automator/metamodels/%.yaml
 	$(RUN) gen-python $< > $@.tmp && mv $@.tmp $@
 
-# tried to find a single meaning for each permissible value
-# unlike term mapping, which can tolerate multiple mapped terms
-target/soil_meanings.yaml: tests/resources/mixs/terms.yaml
-	poetry run enum_annotator \
-		--modelfile $< \
-		--requested_enum_name fao_class_enum \
-		--ontology_string ENVO > $@
-
-# validate that it's still valid LinkML
-# FileNotFoundError: [Errno 2] No such file or directory: '/Users/MAM/Documents/gitrepos/linkml-model-enrichment/target/ranges.yaml'
-# cp tests/resources/mixs/*yaml target
-target/soil_meanings_generated.yaml: target/soil_meanings.yaml
-	poetry run gen-yaml $< > $@
-
-# requires Felix files
-# add demonstration SQL file
-target/availabilities_g_s_strain_202112151116.yaml: local/availabilities_g_s_strain_202112151116.tsv
-	poetry run tsv2linkml \
-		--enum-columns organism \
-		--output $@ \
-		--class_name availabilities \
-		--schema_name availabilities $<
-
-# KeyError: 'iri' could mean that an unrecognized ontology name was used
-target/availabilities_g_s_strain_202112151116_org_meanings.yaml: target/availabilities_g_s_strain_202112151116.yaml
-	poetry run enum_annotator \
-		--modelfile $< \
-		--requested_enum_name organism_enum \
-		--ontology_string NCBITAXON > $@
-
-target/availabilities_g_s_strain_202112151116_org_meanings_curateable.tsv: target/availabilities_g_s_strain_202112151116_org_meanings.yaml
-	poetry run enums_to_curateable \
-		--modelfile $< \
-		--enum organism_enum \
-		--tsv_out $@
-
-# do some curation on target/availabilities_g_s_strain_202112151116_org_meanings_curateable.tsv
-#   and save as target/availabilities_g_s_strain_202112151116_org_meanings_curated.txt
-# Excel wants to call it "*.txt". I'm saving as UTF 16 so I can be sure about the encoding at import time.
-
-target/availabilities_g_s_strain_202112151116_org_meanings_curated.yaml: target/availabilities_g_s_strain_202112151116_org_meanings_curated.txt
-	poetry run curated_to_enums \
-		--tsv_in $< \
-		--tsv_encoding utf_16 \
-		--model_in target/availabilities_g_s_strain_202112151116_org_meanings.yaml \
-		--curated_yaml $@ \
-		--selected_enum organism_enum
 
 # create a convenient wrapper script;
 # this can be used outside the poetry environment
 bin/schemauto:
 	echo `poetry run which schemauto` '"$$@"' > $@ && chmod +x $@
 
+########################
+#### Metamodel docs ####
+########################
+
+all-docs: $(patsubst %,docs-%,$(MODELS))
+
+docs-dosdp: schema_automator/metamodels/dosdp/dosdp_linkml.yaml
+	$(RUN) gen-doc -d docs/metamodels/dosdp $<
+
+docs-%: schema_automator/metamodels/%.yaml
+	$(RUN) gen-doc -d docs/metamodels/$* $<
+
+sphinx-%:
+	cd docs && $(RUN) make $*
+.PHONY: sphinx-%
 
 ################################################
 #### Commands for building the Docker image ####

docs/conf.py

@@ -33,43 +33,43 @@
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
-    'sphinx.ext.autodoc',
-    'sphinx.ext.githubpages',
-    'sphinx.ext.autosectionlabel',
-    'sphinx_pdj_theme',
-    'sphinx_click',
-    'sphinx.ext.viewcode',
-    'sphinx.ext.todo',
-    'sphinx.ext.coverage',
-    'sphinx.ext.autosummary',
-    'myst_parser',
-    'sphinx.ext.intersphinx',
-    'sphinxcontrib.mermaid'
+    "sphinx.ext.autodoc",
+    "sphinx.ext.githubpages",
+    "sphinx.ext.autosectionlabel",
+    "sphinx_pdj_theme",
+    "sphinx_click",
+    "sphinx.ext.viewcode",
+    "sphinx.ext.todo",
+    "sphinx.ext.coverage",
+    "sphinx.ext.autosummary",
+    "myst_parser",
+    "sphinx.ext.intersphinx",
+    "sphinxcontrib.mermaid"
 ]
 
 # The suffix(es) of source filenames.
 # You can specify multiple suffix as a list of string:
-# source_suffix = ['.rst', '.md']
-source_suffix = ['.rst', '.md']
+# source_suffix = [".rst", ".md"]
+source_suffix = [".rst", ".md"]
 
 # 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 = ['_build', 'Thumbs.db', '.DS_Store']
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
 
 
 # -- Options for HTML output -------------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-#html_theme = 'sphinx_pdj_theme'
+#html_theme = "sphinx_pdj_theme"
 #html_theme_path = [sphinx_pdj_theme.get_html_theme_path()]
 
 # 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"]

docs/index.rst

@@ -28,6 +28,7 @@ schema frameworks, including:
    install
    cli
    packages/index
+   metamodels/index
 
 
 Indices and tables

docs/metamodels/index.rst

@@ -0,0 +1,23 @@
+Source Metamodels
+=================
+
+Schema Automator makes use of LinkML Schema representations of source
+metamodels in order to define transformations.
+
+.. toctree::
+   :maxdepth: 3
+   :caption: Contents:
+
+   index
+   cadsr/index
+   frictionless/index
+   dosdp/index
+   fhir/index
+
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`