From c30e9a45f3d1587072034bd0c446516a77609819 Mon Sep 17 00:00:00 2001 From: Abel Soares Siqueira Date: Thu, 29 Aug 2024 14:31:38 +0200 Subject: [PATCH 1/3] Remove docs from minimum profile Introduces a question AddLocalDocumentation to control the existence of the `docs` folder. If the user selects "Online documentation", then "Local documentation" is implied. The logic behind this approach is simply to define the computed variable `AddLocalDocumentation` based on either flag. The downside is that the generated answers will still only show the online flag. Related to #593 --- CHANGELOG.md | 1 + copier/questions/features_documentation.yml | 9 ++++++++- template/project_setup.md.jinja | 2 ++ template/pyproject.toml.jinja | 6 ++++++ .../Makefile.jinja | 0 .../_templates/.gitignore | 0 .../conf.py.jinja | 0 .../index.rst.jinja | 0 .../make.bat.jinja | 0 9 files changed, 17 insertions(+), 1 deletion(-) rename template/{docs => {% if AddLocalDocumentation %}docs{% endif %}}/Makefile.jinja (100%) rename template/{docs => {% if AddLocalDocumentation %}docs{% endif %}}/_templates/.gitignore (100%) rename template/{docs => {% if AddLocalDocumentation %}docs{% endif %}}/conf.py.jinja (100%) rename template/{docs => {% if AddLocalDocumentation %}docs{% endif %}}/index.rst.jinja (100%) rename template/{docs => {% if AddLocalDocumentation %}docs{% endif %}}/make.bat.jinja (100%) diff --git a/CHANGELOG.md b/CHANGELOG.md index fae58d58..b55dd309 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -15,6 +15,7 @@ * Make SonarCloud optional [#515](https://github.com/NLeSC/python-template/pull/515) * Make citation optional [#471](https://github.com/NLeSC/python-template/pull/471) * Make online documentation optional [#476](https://github.com/NLeSC/python-template/pull/476) +* Make local documentation optional [#593](https://github.com/NLeSC/python-template/pull/593) ### Changed * Update the user documentation (README.md) of the template [#575](https://github.com/NLeSC/python-template/pull/623) diff --git a/copier/questions/features_documentation.yml b/copier/questions/features_documentation.yml index 3e025607..53c02b85 100644 --- a/copier/questions/features_documentation.yml +++ b/copier/questions/features_documentation.yml @@ -7,13 +7,16 @@ SelectDocumentationFeatures: type: yaml default: |- {% if template_profile == 'recommended' %} - [AddOnlineDocumentation_flag, AddDevDoc_flag] + [AddLocalDocumentation_flag, AddOnlineDocumentation_flag, AddDevDoc_flag] {%- else -%} [] {%- endif %} help: Select documentation features multiselect: true choices: + Local documentation: + value: AddLocalDocumentation_flag + # validator: "{% if something != 'AnotherThing' %}BlaBla{% endif %}" Online documentation (Read the Docs): value: AddOnlineDocumentation_flag # validator: "{% if something != 'AnotherThing' %}BlaBla{% endif %}" @@ -22,6 +25,10 @@ SelectDocumentationFeatures: # validator: "{% if something != 'AnotherThing' %}BlaBla{% endif %}" # computed features +AddLocalDocumentation: + type: bool + default: "{{ 'AddLocalDocumentation_flag' in SelectDocumentationFeatures or 'AddOnlineDocumentation_flag' in SelectDocumentationFeatures }}" + when: false AddOnlineDocumentation: type: bool default: "{{ 'AddOnlineDocumentation_flag' in SelectDocumentationFeatures }}" diff --git a/template/project_setup.md.jinja b/template/project_setup.md.jinja index 6d4a4b46..c4093c28 100644 --- a/template/project_setup.md.jinja +++ b/template/project_setup.md.jinja @@ -48,6 +48,7 @@ help you decide which tool to use for packaging. - Workflows can be found in [`.github/workflows`](.github/workflows/) - [Relevant section in the guide](https://guide.esciencecenter.nl/#/best_practices/language_guides/python?id=testing) +{% if AddLocalDocumentation -%} ## Documentation - Documentation should be put in the [`docs/`](docs/) directory. The contents have been generated using `sphinx-quickstart` (Sphinx version 1.6.5). @@ -59,6 +60,7 @@ help you decide which tool to use for packaging. - [AutoAPI](https://sphinx-autoapi.readthedocs.io/) is used to generate documentation for the package Python objects. {% if AddOnlineDocumentation %}- `.readthedocs.yaml` is the ReadTheDocs configuration file. When ReadTheDocs is building the documentation this package and its development dependencies are installed so the API reference can be rendered.{% endif -%} - [Relevant section in the guide](https://guide.esciencecenter.nl/#/best_practices/language_guides/python?id=writingdocumentation) +{%- endif %} ## Coding style conventions and code quality diff --git a/template/pyproject.toml.jinja b/template/pyproject.toml.jinja index 0ec6f942..10a61198 100644 --- a/template/pyproject.toml.jinja +++ b/template/pyproject.toml.jinja @@ -55,12 +55,14 @@ dev = [ "tox", "myst_parser", ] +{%- if AddLocalDocumentation %} docs = [ "sphinx", "sphinx_rtd_theme", "sphinx-autoapi", "myst_parser", ] +{%- endif %} publishing = [ "build", "twine", @@ -97,7 +99,9 @@ extras = dev [tool.ruff] line-length = 120 output-format = "concise" +{%- if AddLocalDocumentation %} extend-exclude = ["docs"] +{%- endif %} [tool.ruff.lint] # Allow unused variables when underscore-prefixed. @@ -149,5 +153,7 @@ filename = "pyproject.toml" filename = "CITATION.cff" {%- endif %} +{% if AddLocalDocumentation -%} [[tool.bumpversion.files]] filename = "docs/conf.py" +{%- endif %} diff --git a/template/docs/Makefile.jinja b/template/{% if AddLocalDocumentation %}docs{% endif %}/Makefile.jinja similarity index 100% rename from template/docs/Makefile.jinja rename to template/{% if AddLocalDocumentation %}docs{% endif %}/Makefile.jinja diff --git a/template/docs/_templates/.gitignore b/template/{% if AddLocalDocumentation %}docs{% endif %}/_templates/.gitignore similarity index 100% rename from template/docs/_templates/.gitignore rename to template/{% if AddLocalDocumentation %}docs{% endif %}/_templates/.gitignore diff --git a/template/docs/conf.py.jinja b/template/{% if AddLocalDocumentation %}docs{% endif %}/conf.py.jinja similarity index 100% rename from template/docs/conf.py.jinja rename to template/{% if AddLocalDocumentation %}docs{% endif %}/conf.py.jinja diff --git a/template/docs/index.rst.jinja b/template/{% if AddLocalDocumentation %}docs{% endif %}/index.rst.jinja similarity index 100% rename from template/docs/index.rst.jinja rename to template/{% if AddLocalDocumentation %}docs{% endif %}/index.rst.jinja diff --git a/template/docs/make.bat.jinja b/template/{% if AddLocalDocumentation %}docs{% endif %}/make.bat.jinja similarity index 100% rename from template/docs/make.bat.jinja rename to template/{% if AddLocalDocumentation %}docs{% endif %}/make.bat.jinja From ff5a7e508c95f0dc458cc71a04e4433763e1043b Mon Sep 17 00:00:00 2001 From: Abel Soares Siqueira Date: Thu, 29 Aug 2024 16:42:06 +0200 Subject: [PATCH 2/3] Move AddGitHubActionDocumentation to features_documentation.yml Move AddGitHubActionDocumentation to features_documentation.yml to enable the flag AddLocalDocumentation when AddGitHubActionDocumentation is selected. Related to #593 --- copier/questions/features_code_quality.yml | 9 +-------- copier/questions/features_documentation.yml | 11 +++++++++-- 2 files changed, 10 insertions(+), 10 deletions(-) diff --git a/copier/questions/features_code_quality.yml b/copier/questions/features_code_quality.yml index ea29397f..9d976718 100644 --- a/copier/questions/features_code_quality.yml +++ b/copier/questions/features_code_quality.yml @@ -37,7 +37,7 @@ SelectGitHubActions: type: yaml default: |- {% if template_profile == 'recommended' %} - [AddGitHubActionBuild_flag, AddGitHubActionDocumentation_flag] + [AddGitHubActionBuild_flag] {%- else -%} [] {%- endif %} @@ -47,9 +47,6 @@ SelectGitHubActions: Build: value: AddGitHubActionBuild_flag # validator: "{% if something != 'AnotherThing' %}BlaBla{% endif %}" - Documentation: - value: AddGitHubActionDocumentation_flag - # validator: "{% if something != 'AnotherThing' %}BlaBla{% endif %}" Link checker (reports broken URLs): value: AddLinkCheck_flag # validator: "{% if something != 'AnotherThing' %}BlaBla{% endif %}" @@ -60,10 +57,6 @@ AddGitHubActionBuild: type: bool default: "{{ 'AddGitHubActionBuild_flag' in SelectGitHubActions }}" when: false -AddGitHubActionDocumentation: - type: bool - default: "{{ 'AddGitHubActionDocumentation_flag' in SelectGitHubActions }}" - when: false AddLinkCheck: type: bool default: "{{ 'AddLinkCheck_flag' in SelectGitHubActions }}" diff --git a/copier/questions/features_documentation.yml b/copier/questions/features_documentation.yml index 53c02b85..6316ccbb 100644 --- a/copier/questions/features_documentation.yml +++ b/copier/questions/features_documentation.yml @@ -7,7 +7,7 @@ SelectDocumentationFeatures: type: yaml default: |- {% if template_profile == 'recommended' %} - [AddLocalDocumentation_flag, AddOnlineDocumentation_flag, AddDevDoc_flag] + [AddLocalDocumentation_flag, AddOnlineDocumentation_flag, AddDevDoc_flag, AddGitHubActionDocumentation_flag] {%- else -%} [] {%- endif %} @@ -23,11 +23,14 @@ SelectDocumentationFeatures: Developer documentation: value: AddDevDoc_flag # validator: "{% if something != 'AnotherThing' %}BlaBla{% endif %}" + GitHub Action to build documentation: + value: AddGitHubActionDocumentation_flag + # validator: "{% if something != 'AnotherThing' %}BlaBla{% endif %}" # computed features AddLocalDocumentation: type: bool - default: "{{ 'AddLocalDocumentation_flag' in SelectDocumentationFeatures or 'AddOnlineDocumentation_flag' in SelectDocumentationFeatures }}" + default: "{{ 'AddLocalDocumentation_flag' in SelectDocumentationFeatures or 'AddOnlineDocumentation_flag' in SelectDocumentationFeatures or 'AddGitHubActionDocumentation_flag' in SelectDocumentationFeatures }}" when: false AddOnlineDocumentation: type: bool @@ -37,3 +40,7 @@ AddDevDoc: type: bool default: "{{ 'AddDevDoc_flag' in SelectDocumentationFeatures }}" when: false +AddGitHubActionDocumentation: + type: bool + default: "{{ 'AddGitHubActionDocumentation_flag' in SelectDocumentationFeatures }}" + when: false From 2b0be3e5ee01544aa088650d5429e2a22f3db4b6 Mon Sep 17 00:00:00 2001 From: Abel Soares Siqueira Date: Thu, 29 Aug 2024 21:33:31 +0200 Subject: [PATCH 3/3] Don't add sphinx if local documentation is not selected Remove sphinx related packages from the dev list in pyproject if AddLocalDocumentation is false. Related to #593 --- template/pyproject.toml.jinja | 2 ++ 1 file changed, 2 insertions(+) diff --git a/template/pyproject.toml.jinja b/template/pyproject.toml.jinja index cb5a762c..0757ab6e 100644 --- a/template/pyproject.toml.jinja +++ b/template/pyproject.toml.jinja @@ -51,9 +51,11 @@ dev = [ "pytest-cov", {%- endif %} "ruff", + {%- if AddLocalDocumentation %} "sphinx", "sphinx_rtd_theme", "sphinx-autoapi", + {%- endif %} "tox", "myst_parser", ]