feat(doc-template): adding options for documentation themes (osl-incu…

…bator#292)

.github/workflows/main.yaml

@@ -154,7 +154,10 @@ jobs:
           - auto-format-tools.sh
           - build-systems.sh
           - containers.sh
-          - docs.sh
+          - docs-jupyter-book.sh
+          - docs-mkdocs.sh
+          - docs-quarto.sh
+          - docs-sphinx.sh
           - files.sh
           - linters.sh
           - tests.sh

.makim.yaml

@@ -70,7 +70,10 @@ groups:
           ./tests/smoke/build-systems.sh
           ./tests/smoke/cli.sh
           ./tests/smoke/containers.sh
-          ./tests/smoke/docs.sh
+          ./tests/smoke/docs-jupyter-book.sh
+          ./tests/smoke/docs-mkdocs.sh
+          ./tests/smoke/docs-quarto.sh
+          ./tests/smoke/docs-sphinx.sh
           ./tests/smoke/files.sh
           ./tests/smoke/linters.sh
           ./tests/smoke/tests.sh

docs/guide.md

@@ -397,7 +397,8 @@ project metadata.
 Depending on your taste and the needs of your project, you should choose the
 documentation engine that best suits your needs. SciCookie offers you four
 documentation engine options for your Python package: _mkdocs_, _sphinx-rst_,
-_sphinx-myst_, _jupyter-book_ and _quarto_.
+_sphinx-myst_, _jupyter-book_ and _quarto_. Additionally styling options
+(themes) are provided for your documentation.
 
 - [**mkdocs**](https://www.mkdocs.org/): is a fast, simple, and downright
   gorgeous static site generator for creating project documentation.
@@ -406,8 +407,13 @@ _sphinx-myst_, _jupyter-book_ and _quarto_.
   create clear and well-structured documentation without requiring advanced
   programming skills. _mkdocs_ can be easily integrated with version control
   systems such as Git, supports a variety of predefined themes that allow you to
-  customise the visual appearance of your documentation. In SciCookie, so far,
-  we use the _material_ theme to generate documentation with _mkdocs_.
+  customise the visual appearance of your documentation. In SciCookie you can
+  choose between the
+  [MkDocs (default)](https://www.mkdocs.org/user-guide/choosing-your-theme/#mkdocs),
+  [Material](https://github.com/squidfunk/mkdocs-material),
+  [Cinder](https://github.com/chrissimpkins/cinder) and
+  [readthedocs](https://www.mkdocs.org/user-guide/choosing-your-theme/#readthedocs)
+  themes.
 
 - [**Sphinx**](https://www.sphinx-doc.org/en/master/): _Sphinx_ makes it easy to
   create intelligent and attractive documentation. It provides various output
@@ -419,7 +425,14 @@ _sphinx-myst_, _jupyter-book_ and _quarto_.
   _reStructuredText_ markup language by default and _Sphinx-myst_(Markedly
   Structured Text - Parser) is a Sphinx and Docutils extension to parse MyST, a
   rich and extensible flavour of Markdown for authoring technical and scientific
-  documentation.
+  documentation. Also, SciCookie offers themes to customize the look and feel of
+  your documentation : a clean and minimalist theme (default -
+  [Alabaster](https://sphinx-themes.org/sample-sites/default-alabaster/)), one
+  that is very popular among scientists for its documentation –
+  [Read the Docs](https://sphinx-themes.org/sample-sites/sphinx-rtd-theme/) and
+  another collection of themes for
+  [PyData](https://sphinx-themes.org/sample-sites/pydata-sphinx-theme/) made for
+  a particular kind of data science projects.
 
 - [**Jupyter Book**](https://jupyterbook.org/en/stable/intro.html): allows you
   to create engaging, publication-quality books and documents from computational
@@ -429,16 +442,25 @@ _sphinx-myst_, _jupyter-book_ and _quarto_.
   the look and feel of the book to your needs and extensions to add additional
   features. It can generate books in a variety of output formats, including
   HTML, PDF and static web pages. It integrates well with version control
-  systems such as Git.
+  systems such as Git. If you want to customise the look or style of the
+  documentation, SciCookie lets you choose between the default
+  ([Sphinx Book Theme](https://sphinx-book-theme.readthedocs.io/)) theme or one
+  derived from sphinx such as
+  [Readthedocs](https://sphinx-themes.org/sample-sites/sphinx-rtd-theme/) or
+  [PyData](https://pydata-sphinx-theme.readthedocs.io/en/latest/user_guide/index.html).
 
 - [**Quarto**](https://quarto.org/): It is a versatile open-source platform
   designed for scientific and technical publishing. It offers the unique feature
   of embedding Python code directly into your documentation, enabling
   interactive and dynamic content creation. With Quarto, you can easily render
   your documents in multiple formats such as HTML, PDF, and websites, making it
-  convenient for sharing and presenting your work. Additionally, Quarto provides
-  customization options to personalize your content according to your
-  preferences and needs.
+  convenient for sharing and presenting your work. In addition, Quarto offers
+  customisation options to personalise your content according to your
+  preferences and needs. Through SciCookie, you can choose from some of the
+  themes available in Quarto: [Default](https://bootswatch.com/default/),
+  [Cosmo](https://bootswatch.com/cosmo/),
+  [Cerulean](https://bootswatch.com/cerulean/),
+  [Materia](https://bootswatch.com/materia/).
 
 If you think we should add more options of documentation engines or themes, you
 can submit your suggestion as a issue at

src/scicookie/cookiecutter.json

@@ -25,6 +25,14 @@
     "quarto"
   ],
   "documentation_url": "{{ cookiecutter.project_url }}",
+  "mkdocs_theme": ["default", "material", "cinder", "readthedocs"],
+  "sphinx_theme": ["default", "readthedocs", "pydata"],
+  "jupyter_book_theme": [
+    "default",
+    "pydata-sphinx-theme",
+    "readthedocs-sphinx-theme"
+  ],
+  "quarto_theme": ["default", "cosmo", "cerulean", "materia"],
   "code_of_conduct": [
     "None",
     "contributor-covenant",

src/scicookie/hooks/post_gen_project.py

@@ -121,16 +121,16 @@ def move_selected_doc_dir():
         docs_target_dir = PROJECT_DIRECTORY / "docs"
 
     if DOCUMENTATION_ENGINE.startswith("sphinx"):
+        DOCS_SPHINX = Path(DOCS_SPEC_DIR).parent
+        remove_dir(Path("docs") / "api")
         remove_project_file(Path("docs") / "index.md")
+        shutil.move(DOCS_SPHINX / 'conf.py', docs_target_dir)
+        shutil.move(DOCS_SPHINX / 'make.bat', docs_target_dir)
+        shutil.move(DOCS_SPHINX / 'readme.md', docs_target_dir)
 
     for file_name in os.listdir(DOCS_SPEC_DIR):
         shutil.move(DOCS_SPEC_DIR / file_name, docs_target_dir)
 
-    if DOCUMENTATION_ENGINE.startswith("sphinx"):
-        DOCS_SPHINX = Path(DOCS_SPEC_DIR).parent
-        shutil.move(DOCS_SPHINX / 'conf.py', docs_target_dir)
-        shutil.move(DOCS_SPHINX / 'make.bat', docs_target_dir)
-        shutil.move(DOCS_SPHINX / 'readme.md', docs_target_dir)
 
 
 def clean_up_tests():

src/scicookie/profiles/base.yaml

@@ -131,6 +131,62 @@ documentation_url:
   default: "${{ project_url }}"
   visible: true
 
+mkdocs_theme:
+  message: Select one option for the MkDocs theme
+  help: "For more information, check:\n  https://osl-incubator.github.io/scicookie/guide/#documentation-engine"
+  type: single-choice
+  default: default
+  # first choice is the default for the UI
+  choices:
+    - default
+    - material
+    - cinder
+    - readthedocs
+  visible: ${{ documentation_engine == "mkdocs" }}
+  depends_on:
+    - documentation_engine: mkdocs
+
+sphinx_theme:
+  message: Select one option for the Sphinx theme
+  help: "For more information, check:\n  https://osl-incubator.github.io/scicookie/guide/#documentation-engine"
+  type: single-choice
+  default: default
+  # first choice is the default for the UI
+  choices:
+    - default
+    - readthedocs
+    - pydata
+  visible: ${{ documentation_engine.startswith("sphinx") }}
+
+jupyter_book_theme:
+  message: Select one option for the Jupyter Book theme
+  help: "For more information, check:\n  https://osl-incubator.github.io/scicookie/guide/#documentation-engine"
+  type: single-choice
+  default: default
+  # first choice is the default for the UI
+  choices:
+    - default
+    - pydata-sphinx-theme
+    - readthedocs-sphinx-theme
+  visible: ${{ documentation_engine == "jupyter-book" }}
+  depends_on:
+    - documentation_engine: jupyter-book
+
+quarto_theme:
+  message: Select one option for the Quarto theme
+  help: "For more information, check:\n  https://osl-incubator.github.io/scicookie/guide/#documentation-engine"
+  type: single-choice
+  default: default
+  # first choice is the default for the UI
+  choices:
+    - default
+    - cosmo
+    - cerulean
+    - materia
+  visible: ${{ documentation_engine == "quarto" }}
+  depends_on:
+    - documentation_engine: quarto
+
 use_tools:
   message: Select all the initial tools you want to add to your project
   help: "For more information, check:\n  https://osl-incubator.github.io/scicookie/guide/#project-tools"
@@ -169,11 +225,6 @@ use_containers:
     - Podman
   visible: true
 
-# doc_template:
-#   message: Select the template for the Documentation Engine
-#   help: ""
-#   default: Material
-
 code_of_conduct:
   message: Select one option for the Code of Conduct
   help: "For more information, check:\n  https://osl-incubator.github.io/scicookie/guide/#code-of-conduct"

src/scicookie/profiles/osl.yaml

@@ -45,11 +45,16 @@ command_line_interface:
   visible: true
 
 documentation_engine:
-  visible: true
+  default: mkdocs
+  visible: false
 
 documentation_url:
   visible: true
 
+mkdocs_theme:
+  default: material
+  visible: false
+
 use_tools:
   choices:
     - bandit

src/scicookie/{{cookiecutter.project_slug}}/.makim.yaml

@@ -32,7 +32,7 @@ groups:
         run: |
           {%- if cookiecutter.documentation_engine == "jupyter-book" %}
           rm -rf docs/_build
-          jupyter-book build docs
+          jupyter-book build docs --config docs/_config.yaml
           {%- elif cookiecutter.documentation_engine == "mkdocs" %}
           mkdocs build --config-file mkdocs.yaml
           {%- elif cookiecutter.documentation_engine.startswith("sphinx") %}

src/scicookie/{{cookiecutter.project_slug}}/Makefile

@@ -95,7 +95,7 @@ docs-preview: docs-build
 #NOTE: This command will fail if ({{cookiecutter.git_https_origin}})<- this is not a correct URL.
 .PHONY:docs-build
 docs-build:
-	jupyter-book build --all docs/
+	jupyter-book build docs --config docs/_config.yaml
 
 .PHONY: docs-preview
 docs-preview: docs-build

src/scicookie/{{cookiecutter.project_slug}}/build-system/base/dev-deps-pyproject.toml

@@ -67,19 +67,32 @@ dev = [
   "mkdocs-jupyter >= 0.24.1",
   "mkdocs-literate-nav >= 0.6.0",
   "mkdocs-macros-plugin >= 0.7.0, < 1",
+  {% if cookiecutter.mkdocs_theme == 'material' -%}
   "mkdocs-material >= 9.1.15",
+  {% elif cookiecutter.mkdocs_theme == 'cinder' -%}
+  "mkdocs-cinder >= 1.2.0"
+  {% endif -%}
   "mkdocstrings >= 0.21.2",
   "mkdocstrings-python >= 1.1.2",
 {%- elif cookiecutter.documentation_engine.startswith("sphinx") %}
   "Sphinx >= 6.2.1",
+  {%- if cookiecutter.sphinx_theme == 'readthedocs'%}
   "sphinx-rtd-theme >= 1.2.2",
+  {%- elif cookiecutter.sphinx_theme == 'pydata' %}
+  "pydata-sphinx-theme >= 0.15.3"
+  {%- endif %}
   "importlib-metadata >= 6.5.1",
   "myst-parser >= 0.19.2",
   "nbsphinx >= 0.9.2",
   "pandoc >= 2.3",
 {%- elif cookiecutter.documentation_engine == 'jupyter-book' %}
   "jupyter-book >= 0.15.1",
   "myst-parser >= 0.18.1",
+  {%- if cookiecutter.jupyter_book_theme == 'readthedocs-sphinx-theme'%}
+  "sphinx-rtd-theme >= 1.2.2",
+  {%- elif cookiecutter.jupyter_book_theme == 'pydata-sphinx-theme' %}
+  "pydata-sphinx-theme >= 0.15.3",
+  {% endif %}
 {%- elif cookiecutter.documentation_engine == 'quarto' %}
   "quarto-cli >= 1.4.550",
   "quartodoc >= 0.7.2",

src/scicookie/{{cookiecutter.project_slug}}/build-system/poetry/pyproject.toml

@@ -33,7 +33,7 @@ include = ["{{ package_path }}/py.typed"]
 {% endif -%}
 {# keep this line here #}
 [tool.poetry.dependencies]
-{%- if cookiecutter.documentation_engine == 'quarto' %}
+{%- if cookiecutter.documentation_engine == 'quarto' or cookiecutter.sphinx_theme == 'pydata' or cookiecutter.jupyter_book_theme == 'pydata-sphinx-theme' %}
 python = ">=3.9,<4"
 {% else %}
 python = ">=3.8.1,<4"
@@ -95,13 +95,21 @@ mkdocs-exclude = ">=1.0.2"
 mkdocs-jupyter = ">=0.24.1"
 mkdocs-literate-nav = ">=0.6.0"
 mkdocs-macros-plugin = ">=0.7.0,<1"
+{% if cookiecutter.mkdocs_theme == "material" -%}
 mkdocs-material = ">=9.1.15"
+{% elif cookiecutter.mkdocs_theme == "cinder" -%}
+mkdocs-cinder = ">=1.2.0"
+{% endif -%}
 mkdocstrings = ">=0.21.2"
 mkdocstrings-python = ">=1.1.2"
 {# keep this line here #}
 {%- elif cookiecutter.documentation_engine.startswith("sphinx") %}
 Sphinx = ">=6.2.1"
+{%- if cookiecutter.sphinx_theme == 'readthedocs'%}
 sphinx-rtd-theme = ">=1.2.2"
+{%- elif cookiecutter.sphinx_theme == 'pydata' %}
+pydata-sphinx-theme = ">=0.15.3"
+{%- endif %}
 importlib-metadata = ">=6.5.1"
 myst-parser = ">=0.19.2"
 nbsphinx = ">=0.9.2"
@@ -110,6 +118,11 @@ pandoc = ">=2.3"
 {%- elif cookiecutter.documentation_engine == 'jupyter-book' %}
 jupyter-book = ">=0.15.1"
 myst-parser = ">=0.18.1"
+{%- if cookiecutter.jupyter_book_theme == 'readthedocs-sphinx-theme'%}
+sphinx-rtd-theme = ">= 1.2.2"
+{%- elif cookiecutter.jupyter_book_theme == 'pydata-sphinx-theme' %}
+pydata-sphinx-theme = ">= 0.15.3"
+{% endif %}
 {# keep this line here #}
 {%- elif cookiecutter.documentation_engine == 'quarto' %}
 quarto-cli = ">=1.4.550"

src/scicookie/{{cookiecutter.project_slug}}/docs-jupyter-book/_config.yaml

@@ -3,7 +3,7 @@
 
 title: {{cookiecutter.project_name}}
 author: {{cookiecutter.author_full_name}}
-logo: /images/logo.png
+logo: ./images/logo.png
 
 # Force re-execution of notebooks on each build.
 # See https://jupyterbook.org/content/execute.html
@@ -26,3 +26,13 @@ repository:
 html:
   use_issues_button: true
   use_repository_button: true
+
+{%- if cookiecutter.jupyter_book_theme == 'pydata-sphinx-theme' %}
+sphinx:
+  config:
+    html_theme: pydata_sphinx_theme
+{%- elif cookiecutter.jupyter_book_theme == 'readthedocs-sphinx-theme' %}
+sphinx:
+  config:
+    html_theme: sphinx_rtd_theme
+{% endif %}

src/scicookie/{{cookiecutter.project_slug}}/docs-mkdocs/mkdocs.yaml

@@ -15,10 +15,14 @@ nav:
   - Installation: installation.md
   - Changelog: changelog.md
   - Contributing: contributing.md
-  - API: /api/references.md
+  - API: ./api/references.md
   - Notebook page: example.ipynb
 theme:
-  name: material
+{% if cookiecutter.mkdocs_theme == 'default' %}
+  name: mkdocs
+{% else %}
+  name: {{ cookiecutter.mkdocs_theme }}
+{% endif%}
   features:
     - content.code.annotate
     - content.tabs.link

src/scicookie/{{cookiecutter.project_slug}}/docs-quarto/_quarto.yml

@@ -17,7 +17,7 @@ website:
 
 format:
   html:
-    theme: cosmo
+    theme: {{ cookiecutter.quarto_theme }}
     css: styles.css
     toc: true
 

src/scicookie/{{cookiecutter.project_slug}}/docs-sphinx/conf.py

@@ -86,7 +86,13 @@
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
+{%- if cookiecutter.sphinx_theme == 'readthedocs' %}
 html_theme = "sphinx_rtd_theme"
+{%- elif cookiecutter.sphinx_theme == 'pydata' %}
+html_theme = "pydata_sphinx_theme"
+{%- elif cookiecutter.sphinx_theme == 'default' %}
+html_theme = "alabaster"
+{%- endif %}
 
 # Theme options are theme-specific and customize the look and feel of a
 # theme further.  For a list of options available for each theme, see the