Updating instructions on dev docs and moving Make targets (#264)

CDCgov · Jul 18, 2024 · 1fa6772 · 1fa6772
1 parent ce055af
commit 1fa6772
Show file tree

Hide file tree

Showing 10 changed files with 74 additions and 69 deletions.
diff --git a/docs/source/developer_documentation.rst b/docs/source/developer_documentation.rst
@@ -67,11 +67,11 @@ This entry tells Sphinx to generate documentation for the ``HospitalAdmissions``
 New tutorials
 ~~~~~~~~~~~~~
 
-``PyRenew`` tutorials are `quarto documents <https://quarto.org>`__ located under `./model/docs <https://github.com/CDCgov/multisignal-epi-inference/tree/main/model/docs>`__. Tutorials are automatically rendered using GitHub actions (see the Workflow file `here <https://github.com/CDCgov/multisignal-epi-inference/actions/workflows/website.yaml>`__).
+``PyRenew`` tutorials are `quarto documents <https://quarto.org>`__ located under `./docs/source/tutorials <https://github.com/CDCgov/multisignal-epi-inference/tree/main/docs/source/tutorials>`__. Tutorials are automatically rendered using GitHub actions (see the Workflow file `here <https://github.com/CDCgov/multisignal-epi-inference/actions/workflows/website.yaml>`__).
 
 To make the new tutorial available in the website, developers should follow these steps:
 
-1. Create a new ``quarto`` file in the ``./model/docs`` directory. For instance, the ``example_with_datasets.qmd`` file was added to the repository.
+1. Create a new ``quarto`` file in the ``./docs/source/tutorials`` directory. For instance, the ``example_with_datasets.qmd`` file was added to the repository.
 
 2. Add an entry in the ``./docs/source/tutorials/index.rst``, for example:
 

diff --git a/docs/source/tutorials/Makefile b/docs/source/tutorials/Makefile
@@ -0,0 +1,64 @@
+help:
+	@echo "Available targets"
+	@echo "================="
+	@echo "  help            : Show this help message"
+	@echo "  tutorials       : Render the tutorials"
+	@echo "  tutorials_clean : Remove the generated tutorial files"
+	@echo "  tutorials_md    : Render the tutorials to markdown"
+	@echo "  tutorials_ipynb : Convert the Quarto files to Jupyter notebooks"
+	@echo "  tutorials_py    : Convert the Jupyter notebooks to Python scripts"
+	@echo ""
+
+.PHONY: help tutorials tutorials_md tutorials_rst tutorials_ipynb tutorials_py tutorials_clean
+
+
+# Pattern rule to build a markdown file from a qmd file
+%.md: %.qmd
+	poetry run quarto render $<
+
+# Pattern rule to build a reStructuredText file from a qmd file
+%.rst: %.qmd
+	if [ ! -d $(dir $@) ]; then mkdir rendered_rst; fi
+	poetry run quarto render $< --to rst --output-dir rendered_rst
+	poetry run python ../docs/post_process_rst.py $@
+
+# Pattern rule to build a notebook file from a qmd file
+%.ipynb: %.qmd
+	poetry run quarto convert $< --output $@
+
+# Pattern rule to build a Python file from a notebook file
+%.py: %.ipynb
+	sed -i.bak 's/"cell_type": "raw"/"cell_type": "markdown"/g' $<
+	poetry run jupyter nbconvert --to python $<
+	rm $<.bak
+
+# Automatically get all .qmd files in the docs directory
+QMD_FILES := $(wildcard *.qmd)
+
+# Derive the corresponding markdown files
+MD_FILES := $(QMD_FILES:.qmd=.md)
+
+# Derive the corresponding notebook files
+IPYNB_FILES := $(QMD_FILES:.qmd=.ipynb)
+
+# Derive the corresponding Python files
+PY_FILES := $(IPYNB_FILES:.ipynb=.py)
+
+# Target to build all docs
+tutorials: tutorials_md tutorials_ipynb tutorials_py
+
+# Target to build all markdown files
+tutorials_md: $(MD_FILES)
+
+# Target to build all reStructuredText files
+tutorials_rst: $(RST_FILES)
+
+# Target to build all notebook files
+tutorials_ipynb: $(IPYNB_FILES)
+
+# Target to build all Python files
+tutorials_py: $(PY_FILES)
+
+tutorials_clean:
+	rm -rf docs/*_files/
+	rm -f $(MD_FILES) $(IPYNB_FILES) $(PY_FILES)
diff --git a/docs/source/tutorials/basic_renewal_model.rst b/docs/source/tutorials/basic_renewal_model.rst
@@ -2,4 +2,4 @@
 .. Please do not edit this file directly.
 .. This file is just a placeholder.
 .. For the source file, see:
-.. <https://github.com/CDCgov/multisignal-epi-inference/tree/main/model/docs/basic_renewal_model.qmd>
+.. <https://github.com/CDCgov/multisignal-epi-inference/tree/main/docs/source/tutorials/basic_renewal_model.qmd>
diff --git a/docs/source/tutorials/extending_pyrenew.rst b/docs/source/tutorials/extending_pyrenew.rst
@@ -2,4 +2,4 @@
 .. Please do not edit this file directly.
 .. This file is just a placeholder.
 .. For the source file, see:
-.. <https://github.com/CDCgov/multisignal-epi-inference/tree/main/model/docs/extending_pyrenew.qmd>
+.. <https://github.com/CDCgov/multisignal-epi-inference/tree/main/docs/source/tutorials/extending_pyrenew.qmd>
diff --git a/docs/source/tutorials/getting_started.rst b/docs/source/tutorials/getting_started.rst
@@ -2,4 +2,4 @@
 .. Please do not edit this file directly.
 .. This file is just a placeholder.
 .. For the source file, see:
-.. <https://github.com/CDCgov/multisignal-epi-inference/tree/main/model/docs/getting_started.qmd>
+.. <https://github.com/CDCgov/multisignal-epi-inference/tree/main/docs/source/tutorials/getting_started.qmd>
diff --git a/docs/source/tutorials/hospital_admissions_model.rst b/docs/source/tutorials/hospital_admissions_model.rst
@@ -2,4 +2,4 @@
 .. Please do not edit this file directly.
 .. This file is just a placeholder.
 .. For the source file, see:
-.. <https://github.com/CDCgov/multisignal-epi-inference/tree/main/model/docs/hospital_admissions_model.qmd>
+.. <https://github.com/CDCgov/multisignal-epi-inference/tree/main/docs/source/tutorials/hospital_admissions_model.qmd>
diff --git a/docs/source/tutorials/periodic_effects.rst b/docs/source/tutorials/periodic_effects.rst
@@ -2,4 +2,4 @@
 .. Please do not edit this file directly.
 .. This file is just a placeholder.
 .. For the source file, see:
-.. <https://github.com/CDCgov/multisignal-epi-inference/tree/main/model/docs/periodic_effects.qmd>
+.. <https://github.com/CDCgov/multisignal-epi-inference/tree/main/docs/source/tutorials/periodic_effects.qmd>
diff --git a/docs/source/tutorials/pyrenew_demo.rst b/docs/source/tutorials/pyrenew_demo.rst
@@ -2,4 +2,4 @@
 .. Please do not edit this file directly.
 .. This file is just a placeholder.
 .. For the source file, see:
-.. <https://github.com/CDCgov/multisignal-epi-inference/tree/main/model/docs/pyrenew_demo.qmd>
+.. <https://github.com/CDCgov/multisignal-epi-inference/tree/main/docs/source/tutorials/pyrenew_demo.qmd>
diff --git a/docs/source/tutorials/time.rst b/docs/source/tutorials/time.rst
@@ -2,4 +2,4 @@
 .. Please do not edit this file directly.
 .. This file is just a placeholder.
 .. For the source file, see:
-.. <https://github.com/CDCgov/multisignal-epi-inference/tree/main/model/docs/time.qmd>
+.. <https://github.com/CDCgov/multisignal-epi-inference/tree/main/docs/source/tutorials/time.qmd>
diff --git a/model/Makefile b/model/Makefile
@@ -10,11 +10,6 @@ help:
 	@echo "  help           : Show this help message"
 	@echo "  install        : Install the project dependencies"
 	@echo "  test           : Run the tests"
-	@echo "  docs           : Render the documentation"
-	@echo "  docs_clean     : Remove the generated documentation files"
-	@echo "  docs_md        : Convert the Quarto files to rendered Markdown files"
-	@echo "  docs_ipynb     : Convert the Quarto files to Jupyter notebooks"
-	@echo "  docs_py        : Convert the Jupyter notebooks to Python scripts"
 	@echo "  test_images    : Generate reference images for tests"
 	@echo "  image-build    : Build the podman/Docker image"
 	@echo "  image-run      : Run the podman/Docker image"
@@ -26,59 +21,6 @@ install:
 test:
 	poetry run pytest --mpl --mpl-default-tolerance=10
 
-# Pattern rule to build a markdown file from a qmd file
-docs/%.md: docs/%.qmd
-	poetry run quarto render $<
-
-# Pattern rule to build a reStructuredText file from a qmd file
-docs/%.rst: docs/%.qmd
-	poetry run quarto render $< --to rst
-	poetry run python ../docs/post_process_rst.py $@
-
-# Pattern rule to build a notebook file from a qmd file
-docs/%.ipynb: docs/%.qmd
-	poetry run quarto convert $< --output $@
-
-# Pattern rule to build a Python file from a notebook file
-docs/%.py: docs/%.ipynb
-	sed -i.bak 's/"cell_type": "raw"/"cell_type": "markdown"/g' $<
-	poetry run jupyter nbconvert --to python $<
-	rm $<.bak
-
-# Automatically get all .qmd files in the docs directory
-QMD_FILES := $(wildcard docs/*.qmd)
-
-# Derive the corresponding markdown files
-MD_FILES := $(QMD_FILES:.qmd=.md)
-
-# Derive the corresponding markdown files
-RST_FILES := $(QMD_FILES:.qmd=.rst)
-
-# Derive the corresponding notebook files
-IPYNB_FILES := $(QMD_FILES:.qmd=.ipynb)
-
-# Derive the corresponding Python files
-PY_FILES := $(IPYNB_FILES:.ipynb=.py)
-
-# Target to build all docs
-docs: docs_md docs_ipynb docs_py
-
-# Target to build all markdown files
-docs_md: $(MD_FILES)
-
-# Target to build all reStructuredText files
-docs_rst: $(RST_FILES)
-
-# Target to build all notebook files
-docs_ipynb: $(IPYNB_FILES)
-
-# Target to build all Python files
-docs_py: $(PY_FILES)
-
-docs_clean:
-	rm -rf docs/*_files/
-	rm -f $(MD_FILES) $(RST_FILES) $(IPYNB_FILES) $(PY_FILES)
-
 image-build: Dockerfile
 	$(CONTAINER) build -t pyrenew:latest .
 
@@ -100,5 +42,4 @@ image-push:
 	fi
 	$(CONTAINER) push pyrenew:latest $(CONTAINER_URL)/pyrenew:latest
 
-.PHONY: install test docs docs_md docs_ipynb docs_py docs_clean test_images \
-		image-build image-run
+.PHONY: install test test_images image-build image-run