✨ Add configuration for plot functions (#288)

For details on the 58 (!!!) commits that make up this squashed commit, see #288. 
#288

The main goal was to reduce repetitive boilerplate code (i.e. when changing plot labels).

High level change summary
* ✨ Add configuration for plot functions
* ⬆️🧰 Update tooling
* 🧰📚 Change notebook doc parser to myst-nb (this allows support for mermaid)

Co-authored-by: Joris Snellenburg <[email protected]>

.editorconfig

@@ -10,7 +10,7 @@ insert_final_newline = true
 charset = utf-8
 end_of_line = lf
 
-[*.py]
+[*.{py,ipynb}]
 indent_size = 4
 
 [*.bat]

.github/requirements_min.txt

@@ -2,7 +2,10 @@
 
 cycler==0.10
 numpy==1.22
+docstring-parser==0.16
 matplotlib==3.3
+pydantic==2.0.0
 pyglotaran==0.7.2
+ruamel-yaml==0.18.6
 tabulate==0.8.9
 xarray==2022.3

.github/workflows/test.yml

@@ -108,10 +108,10 @@ jobs:
         run: |
           python -m pip install -U pip wheel
           python -m pip install -r requirements_pinned.txt
-          python -m pip install -U -e ".[test]"
+          python -m pip install -U ".[test]"
 
       - name: Run tests
-        run: python -m pytest --nbval --cov=./ --cov-report term --cov-report xml --cov-config pyproject.toml tests
+        run: python -m pytest --nbval --cov=pyglotaran_extras --cov-report term --cov-report xml --cov-config pyproject.toml tests
 
       - name: Codecov Upload
         continue-on-error: true
@@ -140,14 +140,14 @@ jobs:
         run: |
           python -m pip install -U pip wheel
           python -m pip install -r requirements_pinned.txt
-          python -m pip install -U -e ".[test]"
+          python -m pip install -U ".[test]"
           python -m pip install git+https://github.com/glotaran/pyglotaran
 
       - name: Show installed dependencies
         run: pip freeze
 
       - name: Run tests
-        run: python -m pytest --nbval --cov=./ --cov-report term --cov-report xml --cov-config pyproject.toml tests
+        run: python -m pytest --nbval --cov=pyglotaran_extras --cov-report term --cov-report xml --cov-config pyproject.toml tests
 
       - name: Codecov Upload
         continue-on-error: true

.gitignore

@@ -46,6 +46,8 @@ profile.out
 # Distribution / packaging
 .Python
 env/
+venv/
+.venv/
 build/
 develop-eggs/
 dist/
@@ -93,10 +95,14 @@ coverage.xml
 # Sphinx documentation
 docs/_build/
 docs/api/
+docs/_static
 # documents generated by Sphinx.ext.autosummary
 docs/source/user_documentation/api/*
 # doc figures
 docs/source/images/plot
+# Files generated by the config docs
+pygta_config.schema.json
+docs/config/project/subproject/pygta_config.yml
 
 # PyBuilder
 target/

.pre-commit-config.yaml

@@ -23,7 +23,7 @@ repos:
         args: [--in-place, --config, ./pyproject.toml]
 
   - repo: https://github.com/tox-dev/pyproject-fmt
-    rev: "2.1.3"
+    rev: "2.2.1"
     hooks:
       - id: pyproject-fmt
 
@@ -46,7 +46,7 @@ repos:
 
   - repo: https://github.com/astral-sh/ruff-pre-commit
     # Ruff version.
-    rev: v0.4.7
+    rev: v0.6.2
     hooks:
       - id: ruff
         name: "ruff sort imports notebooks"
@@ -72,11 +72,11 @@ repos:
   # Linters
 
   - repo: https://github.com/pre-commit/mirrors-mypy
-    rev: v1.10.0
+    rev: v1.11.1
     hooks:
       - id: mypy
         exclude: ^docs
-        additional_dependencies: [types-tabulate]
+        additional_dependencies: [types-tabulate, pydantic]
 
   - repo: https://github.com/econchick/interrogate
     rev: 1.7.0
@@ -88,7 +88,7 @@ repos:
 
   - repo: https://github.com/astral-sh/ruff-pre-commit
     # Ruff version.
-    rev: v0.4.7
+    rev: v0.6.2
     hooks:
       - id: ruff
         name: "ruff sort imports"
@@ -103,20 +103,20 @@ repos:
         name: "ruff lint"
 
   - repo: https://github.com/PyCQA/flake8
-    rev: 7.0.0
+    rev: 7.1.1
     hooks:
       - id: flake8
         alias: flake8-docs
         args:
           - "--select=DOC"
-          - "--extend-ignore=DOC502"
+          - "--extend-ignore=DOC502,DOC601,DOC603"
           - "--color=always"
           - "--require-return-section-when-returning-nothing=False"
           - "--allow-init-docstring=True"
           - "--skip-checking-short-docstrings=False"
         name: "flake8 lint docstrings"
         exclude: "^(docs/|tests?/)"
-        additional_dependencies: [pydoclint==0.3.8]
+        additional_dependencies: [pydoclint==0.5.6]
 
   - repo: https://github.com/codespell-project/codespell
     rev: v2.3.0

.ruff-notebooks.toml

@@ -1,7 +1,18 @@
 #:schema https://json.schemastore.org/ruff.json
 extend = ".ruff.toml"
-extend-ignore = ["D", "E402", "F404"]
 
-[isort]
+extend-exclude = [
+  "docs/conf.py",
+]
+
+[lint]
+extend-ignore = [
+  "D",
+  "E402",
+  "F404",
+  "I002", # from __future__ import annotations
+]
+
+[lint.isort]
 required-imports = []
 force-single-line = false

.ruff.toml

@@ -1,48 +1,46 @@
 # Exclude a variety of commonly ignored directories.
 extend-exclude = [
-  "venv",
   "docs/conf.py",
+  "*.ipynb",
 ]
 # Same as Black.
 line-length = 99
 
 # Assume Python 3.10.
 target-version = "py310"
 
-# Enable using ruff with notebooks
-extend-include = ["*.ipynb"]
 
 [lint]
 select = [
-  "E", # pycodestyle
-  "W", # pycodestyle
-  "C", # mccabe
-  "F", # pyflakes
-  "UP", # pyupgrade
-  "D", # pydocstyle
-  "N", # pep8-naming
+  "E",   # pycodestyle
+  "W",   # pycodestyle
+  "C",   # mccabe
+  "F",   # pyflakes
+  "UP",  # pyupgrade
+  "D",   # pydocstyle
+  "N",   # pep8-naming
   "YTT", # flake8-2020
   "BLE", # flake8-blind-except
   # "FBT", # flake8-boolean-trap
-  "B", # flake8-bugbear
-  "C4", # flake8-comprehensions
+  "B",   # flake8-bugbear
+  "C4",  # flake8-comprehensions
   "T10", # flake8-debugger
-  "FA", # flake8-future-annotations
-  "EM", # flake8-errmsg
-  "I", # isort (activates import sorting for formatter)
+  "FA",  # flake8-future-annotations
+  "EM",  # flake8-errmsg
+  "I",   # isort (activates import sorting for formatter)
   "ISC", # flake8-implicit-str-concat
   "INP", # flake8-no-pep420
   "PIE", # flake8-pie
   "T20", # flake8-print
-  "PT", # flake8-pytest-style
+  "PT",  # flake8-pytest-style
   "RSE", # flake8-raise
   "RET", # flake8-return
   "SIM", # flake8-simplify
   "TCH", # flake8-type-checking
   "ARG", # flake8-unused-arguments
   "PTH", # flake8-use-pathlib
   "ERA", # eradicate
-  "PD", # pandas-vet
+  "PD",  # pandas-vet
   "PGH", # pygrep-hooks
   "NPY", # NumPy-specific
   "RUF", # Ruff-specific
@@ -60,13 +58,17 @@ ignore = [
   # Covered by formatter
   "ISC001",
 ]
+external = ["DOC"]
 
 # Allow unused variables when underscore-prefixed.
 dummy-variable-rgx = "^(_+|(_+[a-zA-Z0-9_]*[a-zA-Z0-9]+?))$"
 
 [lint.per-file-ignores]
 "tests/*" = ["ARG001"]
-
+"tests/data/*" = ["INP", "D"]
+"tests/data/config/run_load_config_on_import.py" = [
+  "I002", # from __future__ import annotations
+]
 [lint.isort]
 required-imports = ["from __future__ import annotations"]
 known-first-party = ["pyglotaran_extras"]

docs/conf.py

@@ -17,9 +17,13 @@
 # relative to the documentation root, use os.path.abspath to make it
 # absolute, like shown here.
 #
-
+from pathlib import Path
 import pyglotaran_extras
 
+HERE = Path(__file__).parent
+
+pyglotaran_extras.create_config_schema(HERE/"_static")
+
 # -- General configuration ---------------------------------------------
 
 # If your documentation needs a minimal Sphinx version, state it here.
@@ -33,23 +37,31 @@
     "sphinx.ext.autosummary",
     "sphinx.ext.viewcode",
     "sphinx.ext.napoleon",
-    "myst_parser",
+    "myst_nb",
+    'sphinxcontrib.mermaid',
+    "sphinx_copybutton",
     "sphinx_rtd_theme",
 ]
 
+myst_fence_as_directive = ["mermaid"]
+
 
 autoclass_content = "both"
 autosummary_generate = True
 add_module_names = False
 autodoc_member_order = "bysource"
 
+autodoc_pydantic_model_show_config_summary=False
+autodoc_pydantic_model_show_validator_summary=False
+
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]
 
 # The suffix(es) of source filenames.
 # You can specify multiple suffix as a list of string:
 #
-source_suffix = [".rst", ".md"]
+source_suffix = {'.rst': 'restructuredtext', '.md': 'restructuredtext'}
 # source_suffix = '.rst'
 linkcheck_ignore = [
     r"https://github\.com/glotaran/pyglotaran-extras/actions",
@@ -111,7 +123,7 @@
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-# html_static_path = ["_static"]
+html_static_path = ["_static"]
 
 
 # -- Options for HTMLHelp output ---------------------------------------

docs/config/project/fs_config.yml

@@ -0,0 +1,4 @@
+plotting:
+  general:
+    axis_label_override:
+      time: "Time (fs)"

docs/config/project/pygta_config.yml

@@ -0,0 +1,18 @@
+plotting:
+  general:
+    default_args_override:
+      linlog: true
+      use_svd_number: true
+      linthresh: 2
+    axis_label_override:
+      time: "Time (ps)"
+      spectral: "Wavelength (nm)"
+      data_left_singular_vectors: ""
+      data_singular_values: "Singular Value (a.u.)"
+      data_right_singular_vectors: ""
+  plot_svd:
+    default_args_override:
+      use_svd_number: false
+  plot_overview:
+    default_args_override:
+      show_data: True