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.
Original file line number	Diff line number	Diff line change
		@@ -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.