Merge pull request #123 from linkml/fix_make_vars

Fix make vars quoting and improve docs gen by adding template location and documentation.
linkml · Oct 4, 2024 · 21dc84d · 21dc84d
2 parents b2da87e + 100813d
commit 21dc84d
Show file tree

Hide file tree

Showing 4 changed files with 23 additions and 13 deletions.
diff --git a/{{cookiecutter.project_name}}/Makefile b/{{cookiecutter.project_name}}/Makefile
@@ -11,7 +11,7 @@ SHELL := bash
 ifdef LINKML_ENVIRONMENT_FILENAME
 include ${LINKML_ENVIRONMENT_FILENAME}
 else
-include .env.public
+include config.public.mk
 endif
 
 RUN = poetry run
@@ -22,35 +22,37 @@ SRC = src
 DEST = project
 PYMODEL = $(SRC)/$(SCHEMA_NAME)/datamodel
 DOCDIR = docs
+DOCTEMPLATES = $(SRC)/docs/templates
 EXAMPLEDIR = examples
 SHEET_MODULE = {{cookiecutter.__google_sheet_module}}
 SHEET_ID = $(LINKML_SCHEMA_GOOGLE_SHEET_ID)
 SHEET_TABS = $(LINKML_SCHEMA_GOOGLE_SHEET_TABS)
 SHEET_MODULE_PATH = $(SOURCE_SCHEMA_DIR)/$(SHEET_MODULE).yaml
 
+# Use += to append variables from the variables file
 CONFIG_YAML =
 ifdef LINKML_GENERATORS_CONFIG_YAML
-CONFIG_YAML = ${LINKML_GENERATORS_CONFIG_YAML}
+CONFIG_YAML += ${LINKML_GENERATORS_CONFIG_YAML}
 endif
 
 GEN_DOC_ARGS =
 ifdef LINKML_GENERATORS_DOC_ARGS
-GEN_DOC_ARGS = ${LINKML_GENERATORS_DOC_ARGS}
+GEN_DOC_ARGS += ${LINKML_GENERATORS_DOC_ARGS}
 endif
 
 GEN_OWL_ARGS =
 ifdef LINKML_GENERATORS_OWL_ARGS
-GEN_OWL_ARGS = ${LINKML_GENERATORS_OWL_ARGS}
+GEN_OWL_ARGS += ${LINKML_GENERATORS_OWL_ARGS}
 endif
 
 GEN_JAVA_ARGS =
 ifdef LINKML_GENERATORS_JAVA_ARGS
-GEN_JAVA_ARGS = ${LINKML_GENERATORS_JAVA_ARGS}
+GEN_JAVA_ARGS += ${LINKML_GENERATORS_JAVA_ARGS}
 endif
 
 GEN_TS_ARGS =
 ifdef LINKML_GENERATORS_TYPESCRIPT_ARGS
-GEN_TS_ARGS = ${LINKML_GENERATORS_TYPESCRIPT_ARGS}
+GEN_TS_ARGS += ${LINKML_GENERATORS_TYPESCRIPT_ARGS}
 endif
 
 
@@ -195,7 +197,7 @@ $(DOCDIR):
 	mkdir -p $@
 
 gendoc: $(DOCDIR)
-	cp -rf $(SRC)/docs/* $(DOCDIR) ; \
+	cp -rf $(SRC)/docs/files/* $(DOCDIR) ; \
 	$(RUN) gen-doc ${GEN_DOC_ARGS} -d $(DOCDIR) $(SOURCE_SCHEMA_PATH)
 
 testdoc: gendoc serve

diff --git a/{{cookiecutter.project_name}}/.env.public → ...kiecutter.project_name}}/config.public.mk b/{{cookiecutter.project_name}}/.env.public → ...kiecutter.project_name}}/config.public.mk
@@ -1,13 +1,18 @@
+# config.public.mk
+
 # This file is public in git. No sensitive info allowed.
+# These variables are sourced in Makefile, following make-file conventions.
+# Be aware that this file does not follow python or bash conventions, so may appear a little unfamiliar.
 
 ###### schema definition variables, used by makefile
 
-LINKML_SCHEMA_NAME="{{cookiecutter.__project_slug}}"
-LINKML_SCHEMA_AUTHOR="{{cookiecutter.__author}}"
-LINKML_SCHEMA_DESCRIPTION="{{cookiecutter.project_description}}"
-LINKML_SCHEMA_SOURCE_PATH="{{cookiecutter.__source_path}}"
-LINKML_SCHEMA_GOOGLE_SHEET_ID="{{cookiecutter.google_sheet_id}}"
-LINKML_SCHEMA_GOOGLE_SHEET_TABS="{{cookiecutter.google_sheet_tabs}}"
+# Note: makefile variables should not be quoted, as makefile handles quoting differently than bash
+LINKML_SCHEMA_NAME={{cookiecutter.__project_slug}}
+LINKML_SCHEMA_AUTHOR={{cookiecutter.__author}}
+LINKML_SCHEMA_DESCRIPTION={{cookiecutter.project_description}}
+LINKML_SCHEMA_SOURCE_PATH={{cookiecutter.__source_path}}
+LINKML_SCHEMA_GOOGLE_SHEET_ID={{cookiecutter.google_sheet_id}}
+LINKML_SCHEMA_GOOGLE_SHEET_TABS={{cookiecutter.google_sheet_tabs}}
 
 ###### linkml generator variables, used by makefile
 

diff --git a/...iecutter.project_name}}/src/docs/about.md → ...er.project_name}}/src/docs/files/about.md b/...iecutter.project_name}}/src/docs/about.md → ...er.project_name}}/src/docs/files/about.md
diff --git a/{{cookiecutter.project_name}}/src/docs/templates/README.md b/{{cookiecutter.project_name}}/src/docs/templates/README.md
@@ -0,0 +1,3 @@
+Use this folder to store templates to modify the generated documentation. The templates are written in Jinja2 and are used to generate the HTML documentation for the schema.
+
+The default templates are stored in the linkml repository at https://github.com/linkml/linkml/tree/main/linkml/generators/docgen. If you want to use these as a starting point, you can copy them into this folder and modify them as needed.