From f918529be8a7b1d48194dbc95b64fe7497eaa5b6 Mon Sep 17 00:00:00 2001 From: delucchi-cmu Date: Thu, 8 Jun 2023 20:32:49 -0400 Subject: [PATCH 1/5] Make docs optional --- copier.yml | 11 ++++++++++- python-project-template/pyproject.toml.jinja | 4 ++++ ... {% if include_docs %}.readthedocs.yml{% endif %}} | 0 .../Makefile.jinja | 0 .../conf.py.jinja | 0 .../index.rst.jinja | 0 .../notebooks/README.md | 0 ...nclude_notebooks %}intro_notebook.ipynb{% endif %} | 0 .../requirements.txt.jinja | 0 ...{% if include_notebooks %}notebooks.rst{% endif %} | 0 10 files changed, 14 insertions(+), 1 deletion(-) rename python-project-template/{.readthedocs.yml => {% if include_docs %}.readthedocs.yml{% endif %}} (100%) rename python-project-template/{docs => {% if include_docs %}docs{% endif %}}/Makefile.jinja (100%) rename python-project-template/{docs => {% if include_docs %}docs{% endif %}}/conf.py.jinja (100%) rename python-project-template/{docs => {% if include_docs %}docs{% endif %}}/index.rst.jinja (100%) rename python-project-template/{docs => {% if include_docs %}docs{% endif %}}/notebooks/README.md (100%) rename python-project-template/{docs => {% if include_docs %}docs{% endif %}}/notebooks/{% if include_notebooks %}intro_notebook.ipynb{% endif %} (100%) rename python-project-template/{docs => {% if include_docs %}docs{% endif %}}/requirements.txt.jinja (100%) rename python-project-template/{docs => {% if include_docs %}docs{% endif %}}/{% if include_notebooks %}notebooks.rst{% endif %} (100%) diff --git a/copier.yml b/copier.yml index 0e4be5e4..98a05a20 100644 --- a/copier.yml +++ b/copier.yml @@ -81,6 +81,15 @@ create_example_module: no: false when: "{{ custom_install }}" +include_docs: + help: Do you want to include a directory for sphinx, and autoapi generation? + type: bool + default: yes + choices: + yes: true + no: false + when: "{{ custom_install }}" + include_notebooks: help: Do you want to include rendered notebooks in your documentation? type: bool @@ -88,7 +97,7 @@ include_notebooks: choices: yes: true no: false - when: "{{ custom_install }}" + when: "{{ custom_install and include_docs }}" use_gitlfs: help: Do you want to add a .gitattributes with entries for git-lfs (see https://lincc-ppt.readthedocs.io/en/latest/practices/git-lfs.html)? diff --git a/python-project-template/pyproject.toml.jinja b/python-project-template/pyproject.toml.jinja index a4df3814..d00da7a7 100644 --- a/python-project-template/pyproject.toml.jinja +++ b/python-project-template/pyproject.toml.jinja @@ -19,7 +19,9 @@ classifiers = [ ] dynamic = ["version"] dependencies = [ +{%- if include_notebooks %} "ipykernel", # Support for Jupyter notebooks +{%- endif %} ] # On a mac, install optional dependencies with `pip install '.[dev]'` (include the single quotes) @@ -28,9 +30,11 @@ dev = [ "pytest", "pytest-cov", # Used to report total code coverage "pre-commit", # Used to run checks before finalizing a git commit +{%- if include_docs %} "sphinx==6.1.3", # Used to automatically generate documentation "sphinx-rtd-theme==1.2.0", # Used to render documentation "sphinx-autoapi==2.0.1", # Used to automatically generate api documentation +{%- endif %} {%- if preferred_linter == 'pylint' %} "pylint", # Used for static linting of files {%- elif preferred_linter == 'black' %} diff --git a/python-project-template/.readthedocs.yml b/python-project-template/{% if include_docs %}.readthedocs.yml{% endif %} similarity index 100% rename from python-project-template/.readthedocs.yml rename to python-project-template/{% if include_docs %}.readthedocs.yml{% endif %} diff --git a/python-project-template/docs/Makefile.jinja b/python-project-template/{% if include_docs %}docs{% endif %}/Makefile.jinja similarity index 100% rename from python-project-template/docs/Makefile.jinja rename to python-project-template/{% if include_docs %}docs{% endif %}/Makefile.jinja diff --git a/python-project-template/docs/conf.py.jinja b/python-project-template/{% if include_docs %}docs{% endif %}/conf.py.jinja similarity index 100% rename from python-project-template/docs/conf.py.jinja rename to python-project-template/{% if include_docs %}docs{% endif %}/conf.py.jinja diff --git a/python-project-template/docs/index.rst.jinja b/python-project-template/{% if include_docs %}docs{% endif %}/index.rst.jinja similarity index 100% rename from python-project-template/docs/index.rst.jinja rename to python-project-template/{% if include_docs %}docs{% endif %}/index.rst.jinja diff --git a/python-project-template/docs/notebooks/README.md b/python-project-template/{% if include_docs %}docs{% endif %}/notebooks/README.md similarity index 100% rename from python-project-template/docs/notebooks/README.md rename to python-project-template/{% if include_docs %}docs{% endif %}/notebooks/README.md diff --git a/python-project-template/docs/notebooks/{% if include_notebooks %}intro_notebook.ipynb{% endif %} b/python-project-template/{% if include_docs %}docs{% endif %}/notebooks/{% if include_notebooks %}intro_notebook.ipynb{% endif %} similarity index 100% rename from python-project-template/docs/notebooks/{% if include_notebooks %}intro_notebook.ipynb{% endif %} rename to python-project-template/{% if include_docs %}docs{% endif %}/notebooks/{% if include_notebooks %}intro_notebook.ipynb{% endif %} diff --git a/python-project-template/docs/requirements.txt.jinja b/python-project-template/{% if include_docs %}docs{% endif %}/requirements.txt.jinja similarity index 100% rename from python-project-template/docs/requirements.txt.jinja rename to python-project-template/{% if include_docs %}docs{% endif %}/requirements.txt.jinja diff --git a/python-project-template/docs/{% if include_notebooks %}notebooks.rst{% endif %} b/python-project-template/{% if include_docs %}docs{% endif %}/{% if include_notebooks %}notebooks.rst{% endif %} similarity index 100% rename from python-project-template/docs/{% if include_notebooks %}notebooks.rst{% endif %} rename to python-project-template/{% if include_docs %}docs{% endif %}/{% if include_notebooks %}notebooks.rst{% endif %} From 53e78c8f1400407dbe276fce21f58d6a93149cf1 Mon Sep 17 00:00:00 2001 From: delucchi-cmu Date: Thu, 8 Jun 2023 20:46:59 -0400 Subject: [PATCH 2/5] Pick up more changes --- ... => {% if include_docs %}build-documentation.yml{% endif %}} | 0 python-project-template/.pre-commit-config.yaml.jinja | 2 +- 2 files changed, 1 insertion(+), 1 deletion(-) rename python-project-template/.github/workflows/{build-documentation.yml.jinja => {% if include_docs %}build-documentation.yml{% endif %}} (100%) diff --git a/python-project-template/.github/workflows/build-documentation.yml.jinja b/python-project-template/.github/workflows/{% if include_docs %}build-documentation.yml{% endif %} similarity index 100% rename from python-project-template/.github/workflows/build-documentation.yml.jinja rename to python-project-template/.github/workflows/{% if include_docs %}build-documentation.yml{% endif %} diff --git a/python-project-template/.pre-commit-config.yaml.jinja b/python-project-template/.pre-commit-config.yaml.jinja index cfbc66b4..0997aaaa 100644 --- a/python-project-template/.pre-commit-config.yaml.jinja +++ b/python-project-template/.pre-commit-config.yaml.jinja @@ -158,7 +158,7 @@ repos: "-D", # Flag to override settings in conf.py "exclude_patterns=notebooks/*", # Exclude our notebooks from pre-commit ] -{%- else %} +{%- elif include_docs %} # Make sure Sphinx can build the documentation without issues. - repo: local hooks: From 1ef38563e446965857926efc0fe41851c05bbb30 Mon Sep 17 00:00:00 2001 From: delucchi-cmu Date: Thu, 8 Jun 2023 20:56:50 -0400 Subject: [PATCH 3/5] Picking up changes --- ...{% if include_docs %}build-documentation.yml{% endif %}.jinja} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename python-project-template/.github/workflows/{{% if include_docs %}build-documentation.yml{% endif %} => {% if include_docs %}build-documentation.yml{% endif %}.jinja} (100%) diff --git a/python-project-template/.github/workflows/{% if include_docs %}build-documentation.yml{% endif %} b/python-project-template/.github/workflows/{% if include_docs %}build-documentation.yml{% endif %}.jinja similarity index 100% rename from python-project-template/.github/workflows/{% if include_docs %}build-documentation.yml{% endif %} rename to python-project-template/.github/workflows/{% if include_docs %}build-documentation.yml{% endif %}.jinja From 26d9cf4611b14f322d684eb41d0d2c421d7f148a Mon Sep 17 00:00:00 2001 From: delucchi-cmu Date: Mon, 12 Jun 2023 07:53:37 -0400 Subject: [PATCH 4/5] Add CI test for docs exclusion --- .github/workflows/ci.yml | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 78f35fd3..98ec8ff5 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -64,6 +64,14 @@ jobs: --data include_notebooks=no --data use_gitlfs=disabled foldername: 'pylint_w_o_example_module' + - name: No sphinx docs + package_name: 'drewtonian' + extra_flags: >- + --data project_name=new_science + --data package_name=drewtonian + --data include_docs=no + foldername: 'no_sphinx_docs' + steps: - name: Checkout code From 6e039c38e16e553309cefb2728c632d6c142ef0a Mon Sep 17 00:00:00 2001 From: delucchi-cmu Date: Mon, 12 Jun 2023 08:16:36 -0400 Subject: [PATCH 5/5] Whoops. --- .github/workflows/ci.yml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 98ec8ff5..49626875 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -70,6 +70,7 @@ jobs: --data project_name=new_science --data package_name=drewtonian --data include_docs=no + --data include_notebooks=no foldername: 'no_sphinx_docs' steps: @@ -133,6 +134,7 @@ jobs: cat ../test/${{ matrix.copier_config.foldername }}/docs/requirements.txt - name: Build docs + if: ${{ !contains(matrix.copier_config.extra_flags, 'include_docs=no') }} run: | cd ../test/${{ matrix.copier_config.foldername }} sphinx-build -T -E -b html -d docs/build/doctrees ./docs docs/build/html