diff --git a/docs/source/developer_documentation.rst b/docs/source/developer_documentation.rst index c017d2d4..778a2f57 100644 --- 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 new file mode 100644 index 00000000..56dbcfb9 --- /dev/null +++ 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 index 7b6407d8..10a033e5 100644 --- 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 index 1e385928..9b35ba5a 100644 --- 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 index a3d7e69f..35b58b95 100644 --- 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 index 3323aee6..70fcc980 100644 --- 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 index 490cc082..a9f82f78 100644 --- 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 index 5f803664..accf1a3a 100644 --- 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 index d65e12ed..dd83bcba 100644 --- 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 index 5e2a6baf..c42324a2 100644 --- 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