Modify existing and add new delta method transformations and begin work on documentation

.github/workflows/build.yml

@@ -0,0 +1,33 @@
+name: build
+
+on:
+  push:
+    branches:
+      - "*"
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+    - name: Set up Python 3.12
+      uses: actions/setup-python@v5
+      with:
+        python-version: "3.12"
+    - name: Install dependencies
+      run: python -m pip install .[test] --upgrade pip --no-cache-dir
+    - name: Test with pytest
+      run: pytest # --cov=./ --cov-report=xml
+      # repository > settings > github apps > configure codecov
+
+    # - name: Build package distribution
+    #   if: startsWith(github.ref, 'refs/tags')
+    #   run: |
+    #     python -m pip install build
+    #     python -m build --sdist --wheel --outdir dist/ .
+    # - name: Publish package distribution to PyPI
+    #   if: startsWith(github.ref, 'refs/tags')
+    #   uses: pypa/gh-action-pypi-publish@master
+    #   with:
+    #     skip_existing: true
+    #     user: __token__
+    #     password: ${{ secrets.PYPI_API_TOKEN }}

.github/workflows/deploy.yml

@@ -0,0 +1,59 @@
+name: deploy
+
+on:
+  push:
+    tags:
+      - "v[0-9]+.[0-9]+.[0-9]+"
+
+permissions:
+  contents: write
+
+jobs:
+  pypi:
+    if: false
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python 3.12
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install dependencies
+        run: python -m pip install build . --upgrade pip
+      # - name: Build package distribution
+      #   run: python-m build --sdist --wheel --outdir dist/ .
+      # - name: Publish package distribution to PyPI
+      #   uses: pypa/gh-action-pypi-publish@release/v1
+      #   with:
+      #     skip_existing: true
+      #     user: __token__
+      #     password: ${{ secrets.PYPI_API_TOKEN }}
+
+  docs:
+    runs-on: ubuntu-latest
+    permissions:
+      pages: write
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python 3.12
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install dependencies
+        run: python -m pip install .[docs] --upgrade pip
+      - name: Generate API docs & Build sphinx documentation
+        run: |
+          git fetch --tags
+          cd docs
+          python build.py
+          cd ..
+      - name: Setup Pages
+        uses: actions/configure-pages@v5
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: './docs/pages'
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -1,3 +1,5 @@
+**/.DS_Store
+
 # Byte-compiled / optimized / DLL files
 __pycache__/
 *.py[cod]

.vscode/launch.json

@@ -0,0 +1,15 @@
+{
+  // Use IntelliSense to learn about possible attributes.
+  // Hover to view descriptions of existing attributes.
+  // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "name": "Python Debugger: Current File",
+      "type": "debugpy",
+      "request": "launch",
+      "program": "${file}",
+      "console": "integratedTerminal"
+    }
+  ]
+}

.vscode/settings.json

@@ -0,0 +1,15 @@
+{
+  "[python]": {
+      "editor.defaultFormatter": "charliermarsh.ruff",
+      "editor.formatOnSave": true,
+      "editor.codeActionsOnSave": {
+          "source.organizeImports": "explicit",
+      },
+      "editor.rulers": [80],
+  },
+  "python.testing.pytestArgs": [
+    "tests"
+  ],
+  "python.testing.unittestEnabled": false,
+  "python.testing.pytestEnabled": true,
+}

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/_static/css/custom.css

@@ -0,0 +1,19 @@
+/* reduce the size of the main text */
+p {
+  font-size: 0.95rem;
+}
+
+h1,
+h2,
+h3,
+h4,
+h5,
+h6 {
+  font-weight: 500;
+}
+
+.sidebar-brand-text {
+  font-size: 1rem;
+  font-weight: 500;
+  margin: auto;
+}

docs/_templates/sidebar/variant-selector.html

@@ -0,0 +1,15 @@
+<div class="sidebar-tree">
+  <ul>
+  <li class="toctree-l1 has-children"><a class="reference internal" href="">Versions</a>
+    <input class="toctree-checkbox" id="toctree-checkbox-version" name="toctree-checkbox-version" role="switch" type="checkbox"/>
+    <label for="toctree-checkbox-version"><div class="visually-hidden">Toggle navigation of Versions</div>
+      <i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i>
+    </label>
+    <ul>
+    {% for version in versions %}
+      <li class="toctree-l2"><a class="reference internal" href="{{ pathto('/'.join(['..', version, pagename])) }}">{{ version }}</a></li>
+    {% endfor %}
+    </ul>
+  <li>
+  </ul>
+</div>

docs/api_reference/example.rst

@@ -0,0 +1,5 @@
+pypkg.example
+=============
+
+.. automodule:: pypkg.example
+   :members:

docs/api_reference/index.rst

@@ -0,0 +1,13 @@
+API reference
+=============
+
+.. toctree::
+   :hidden:
+   :glob:
+
+   *
+
+.. note::
+   Briefly describe the organization of the API reference if any.
+
+In PyPkg, we only provide a dummy function :py:func:`.example.add` to show the bone structure of a Python pacakge.

docs/build.py

@@ -0,0 +1,41 @@
+import functools
+import subprocess
+
+import tomllib
+
+run = functools.partial(subprocess.run, shell=True)
+
+
+def build_doc(version: str) -> None:
+    run(f"git checkout v{version}")
+    run("git checkout main -- conf.py")
+    run("git checkout main -- versions.toml")
+
+    run("make html")
+    run(f"mv _build/html pages/{version}")
+    run("rm -rf _build")
+    run("git checkout main")
+
+
+def build_init_page(version: str) -> None:
+    with open("pages/index.html", "w") as f:
+        f.write(f"""<!doctype html>
+<meta http-equiv="refresh" content="0; url=./{version}/">""")
+
+
+if __name__ == "__main__":
+    # create pages folder
+    run("rm -rf pages")
+    run("mkdir pages")
+
+    # get versions
+    with open("meta.toml", "rb") as f:
+        versions = tomllib.load(f)["versions"]
+    versions.sort(reverse=True, key=lambda v: tuple(map(int, v.split("."))))
+
+    # build documentations for different versions
+    for version in versions:
+        build_doc(version)
+
+    # build initial page that redirect to the latest version
+    build_init_page(versions[0])

docs/conf.py

@@ -0,0 +1,106 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+# import os
+# import sys
+# sys.path.insert(0, os.path.abspath("."))
+import datetime
+
+import tomllib
+
+with open("../pyproject.toml", "rb") as f:
+    about = tomllib.load(f)["project"]
+
+
+# -- Project information -----------------------------------------------------
+
+project = about["name"]
+author = ", ".join([info["name"] for info in about["authors"]])
+copyright = f"2019-{datetime.datetime.today().year}, {author}"
+
+
+# The full version, including alpha/beta/rc tags
+version = about["version"]
+
+
+# -- General configuration ---------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named "sphinx.ext.*") or your custom
+# ones.
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.autosectionlabel",
+    "sphinx.ext.extlinks",
+    "sphinx.ext.intersphinx",
+    "sphinx.ext.mathjax",
+    "sphinx.ext.todo",
+    "sphinx.ext.viewcode",
+    "sphinx.ext.napoleon",
+]
+autodoc_typehints = "description"
+autodoc_member_order = "bysource"
+autodoc_type_aliases = {
+    "ArrayLike": "ArrayLike",
+    "NDArray": "NDArray",
+    "DataFrame": "DataFrame",
+}
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ["_templates"]
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = "furo"
+
+# 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_css_files = ["css/custom.css"]
+html_title = f"{project} {version}"
+html_theme_options = {
+    "sidebar_hide_name": False,
+    "light_logo": "logo/logo-light.png",
+    "dark_logo": "logo/logo-dark.png",
+    "light_css_variables": {
+        "color-brand-primary": "#008080",
+        "color-brand-content": "#008080",
+        "color-problematic": "#BF5844",
+        "color-background-secondary": "#F8F8F8",
+        "color-admonition-title--note": "#008080",
+        "color-admonition-title-background--note": "#00808033",
+    },
+    "dark_css_variables": {
+        "color-brand-primary": "#6FD8D1",
+        "color-brand-content": "#6FD8D1",
+        "color-problematic": "#FA9F50",
+        "color-background-secondary": "#202020",
+        "color-admonition-title--note": "#6FD8D1",
+        "color-admonition-title-background--note": "#6FD8D133",
+    },
+}
+# get versions
+with open("meta.toml", "rb") as f:
+    versions = tomllib.load(f)["versions"]
+html_context = {
+    "versions": versions,
+}