Merge pull request #99 from espdev/update-docs-theme

espdev · web-flow · commit 0aec099be1a1 · 2025-04-15T23:25:56.000+01:00
Update docs theme to Furo
diff --git a/.github/workflows/main.yaml b/.github/workflows/main.yaml
@@ -56,7 +56,7 @@ jobs:
           key: venv-${{ hashFiles('poetry.lock') }}
 
       - name: Install the project dependencies
-        run: poetry install -E docs
+        run: poetry install
 
       - name: Run static analysis, linters and mypy
         run: poetry run poe check
diff --git a/.github/workflows/release.yaml b/.github/workflows/release.yaml
@@ -45,9 +45,7 @@ jobs:
           key: venv-${{ hashFiles('poetry.lock') }}
 
       - name: Build
-        run: |
-          poetry install
-          poetry build
+        run: poetry build
 
       - name: Get package version to create a new tag and release
         id: get-version
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -16,9 +16,9 @@ repos:
         language: system
         types: [ python ]
         require_serial: true
-      - id: check-types
-        name: check-types
-        entry: poetry run poe check-types-pre-commit
-        language: system
-        types: [ python ]
-        require_serial: true
+#      - id: check-types
+#        name: check-types
+#        entry: poetry run poe check-types-pre-commit
+#        language: system
+#        types: [ python ]
+#        require_serial: true
diff --git a/.readthedocs.yml b/.readthedocs.yml
@@ -8,7 +8,14 @@ version: 2
 build:
   os: ubuntu-lts-latest
   tools:
-    python: "3.11"
+    python: "3.12"
+
+  # https://docs.readthedocs.com/platform/stable/build-customization.html#install-dependencies-with-poetry~
+  jobs:
+    post_install:
+      - pip install poetry
+      - VIRTUAL_ENV=$READTHEDOCS_VIRTUALENV_PATH poetry install --with docs
+
 
 # Build documentation in the docs/ directory with Sphinx
 sphinx:
@@ -18,11 +25,3 @@ sphinx:
 # Optionally build your docs in additional formats such as PDF and ePub
 formats:
   - pdf
-
-# Optionally set the version of Python and requirements required to build your docs
-python:
-  install:
-    - method: pip
-      path: .
-      extra_requirements:
-        - docs
diff --git a/docs/_static/logo-dark-mode.png b/docs/_static/logo-dark-mode.png
diff --git a/docs/_static/logo.png b/docs/_static/logo.png
diff --git a/docs/conf.py b/docs/conf.py
@@ -19,8 +19,8 @@
 # -- Project information -----------------------------------------------------
 
 project = 'csaps'
-copyright = '2017-2025, Eugene Prilepin'  # noqa
 author = 'Eugene Prilepin'
+copyright = f'2017-2025, {author}'  # noqa
 
 
 def _get_version():
@@ -47,7 +47,9 @@ def _get_version():
     'm2r2',
 ]
 
-intersphinx_mapping = {'scipy': ('https://docs.scipy.org/doc/scipy/reference/', None)}
+intersphinx_mapping = {
+    'scipy': ('https://docs.scipy.org/doc/scipy/reference/', None),
+}
 
 # Extension settings
 plot_apply_rcparams = True
@@ -69,7 +71,7 @@ def _get_version():
 from mpl_toolkits.mplot3d import Axes3D
 from csaps import csaps
 
-plt.style.use('ggplot')
+plt.style.use('csaps.mplstyle')
 
 def univariate_data(n=25, seed=1234):
     np.random.seed(seed)
@@ -95,23 +97,22 @@ def univariate_data(n=25, seed=1234):
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
-#
-html_theme = 'alabaster'
+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']
 
+pygments_style = 'tango'
+pygments_dark_style = 'stata-dark'
+
 html_theme_options = {
-    'fixed_sidebar': 'true',
-    'show_powered_by': 'false',
-    'description': 'Cubic spline approximation (smoothing)',
-    'github_user': 'espdev',
-    'github_repo': 'csaps',
-    'github_type': 'star',
-    'extra_nav_links': {
-        'GitHub repository': 'https://github.com/espdev/csaps',
-        'PyPI': 'https://pypi.org/project/csaps',
-    },
+    'light_logo': 'logo.png',
+    'dark_logo': 'logo-dark-mode.png',
+    'sidebar_hide_name': True,
+    'source_repository': 'https://github.com/espdev/csaps',
+    'source_branch': 'master',
+    'source_directory': 'docs/',
+    'top_of_page_buttons': ['view'],
 }
diff --git a/docs/csaps.mplstyle b/docs/csaps.mplstyle
@@ -0,0 +1,49 @@
+# based on Matplotlib ggplot.mplstyle
+# https://github.com/matplotlib/matplotlib/blob/main/lib/matplotlib/mpl-data/stylelib/ggplot.mplstyle
+
+patch.linewidth: 0.5
+patch.facecolor: 348ABD  # blue
+patch.edgecolor: EEEEEE
+patch.antialiased: True
+
+font.size: 10.0
+
+axes.facecolor: none
+axes.edgecolor: none
+axes.linewidth: 1
+axes.grid: True
+axes.titlesize: x-large
+axes.labelsize: large
+axes.labelcolor: 555555
+axes.axisbelow: True       # grid/ticks are below elements (e.g., lines, text)
+axes.titlecolor: 555555
+
+axes.prop_cycle: cycler('color', ['E24A33', '348ABD', '988ED5', '777777', 'FBC15E', '8EBA42', 'FFB5B8'])
+                   # E24A33 : red
+                   # 348ABD : blue
+                   # 988ED5 : purple
+                   # 777777 : gray
+                   # FBC15E : yellow
+                   # 8EBA42 : green
+                   # FFB5B8 : pink
+
+axes3d.grid: True
+axes3d.xaxis.panecolor: none
+axes3d.yaxis.panecolor: none
+axes3d.zaxis.panecolor: none
+
+xtick.color: 555555
+xtick.direction: out
+
+ytick.color: 555555
+ytick.direction: out
+
+grid.color: C9C9C9
+grid.linestyle: -    # solid line
+
+legend.facecolor: none
+legend.edgecolor: none
+legend.labelcolor: 555555
+
+figure.facecolor: white
+figure.edgecolor: 0.50
diff --git a/docs/formulation.rst b/docs/formulation.rst
@@ -89,7 +89,8 @@ It is an example plot of comparison ``csaps`` and ``scipy.UnivariateSpline`` (k=
     plt.plot(x, y, 'o')
     plt.plot(xi, yi_scipy, '-', label='scipy UnivariateSpline')
     plt.plot(xi, yi_csaps, '-', label='csaps')
-    plt.legend()
+
+    plt.legend(bbox_to_anchor=(0, 1, 1, 0), loc="lower center", ncol=2)
 
 
 .. rubric:: Footnotes
diff --git a/docs/index.rst b/docs/index.rst
@@ -5,6 +5,9 @@ csaps
 
 CSAPS -- Cubic Spline Approximation (Smoothing)
 
+Version:
+|release|
+
 Overview
 --------
 
@@ -38,27 +41,37 @@ You can install and update csaps using pip:
 
     pip install -U csaps
 
+or using modern packaging tools like Poetry:
+
+.. code-block:: bash
+
+    poetry add csaps
+
+
 The module depends only on NumPy and SciPy.
 
 Python 3.10 or above is supported.
 
-Content
--------
-
 .. toctree::
-    :maxdepth: 2
+    :caption: User Guide
+    :hidden:
 
     formulation
     tutorial
     internals
     benchmarks
-    api
     changelog
 
+.. toctree::
+    :caption: API
+    :hidden:
+
+    api
+    genindex
 
-Indices and Tables
-==================
+.. toctree::
+    :caption: Project Links
+    :hidden:
 
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
+    GitHub <https://github.com/espdev/csaps>
+    PyPI <https://pypi.org/project/csaps>
diff --git a/docs/tutorial.rst b/docs/tutorial.rst
@@ -122,7 +122,7 @@ The same weights vector and the same smoothing parameter will be used for all Y
     ax = fig.add_subplot(111, projection='3d')
     ax.set_facecolor('none')
     ax.plot(x, y, z, '.:')
-    ax.plot(xi, yi, zi, '-')
+    ax.plot(xi, yi, zi, '-', linewidth=2)
 
 
 N-D grid Smoothing
@@ -225,14 +225,11 @@ The example of auto smoothing univariate data:
     x, y = univariate_data()
     xi = np.linspace(x[0], x[-1], 51)
 
-    smoothing_result = csaps(x, y, xi)
-
-    yi = smoothing_result.values
-    smooth = smoothing_result.smooth
+    yi, smooth = csaps(x, y, xi)
 
     plt.plot(x, y, 'o')
-    plt.plot(xi, yi, '-', label=f'smooth={smooth:.3f}')
-    plt.legend()
+    plt.plot(xi, yi, '-', label=f'smooth={smooth:.4f}')
+    plt.legend(bbox_to_anchor=(0, 1, 1, 0), loc="lower center")
 
 In ND-gridded data case we can use auto smoothing for all dimensions or the particular dimensions:
 
@@ -268,9 +265,9 @@ The following example demonstartes these two boundary cases:
     yi_1 = csaps(x, y, xi, smooth=1)
 
     plt.plot(x, y, 'o:')
-    plt.plot(xi, yi_0, '-', label='smooth=0')
-    plt.plot(xi, yi_1, '-', label='smooth=1')
-    plt.legend()
+    plt.plot(xi, yi_0, '-', label='smooth=0.0')
+    plt.plot(xi, yi_1, '-', label='smooth=1.0')
+    plt.legend(bbox_to_anchor=(0, 1, 1, 0), loc="lower center", ncol=2)
 
 
 Weighted Smoothing
@@ -303,7 +300,7 @@ The example of weighted smoothing univariate data:
     plt.plot(x, y, 'o')
     plt.plot(xi, yi, '-', label='unweighted')
     plt.plot(xi, yi_w, '-', label='weighted')
-    plt.legend()
+    plt.legend(bbox_to_anchor=(0, 1, 1, 0), loc="lower center", ncol=2)
 
 In n-d gridded data case we can use the same weights for all dimensions or different
 weights for each dimension.
@@ -377,6 +374,11 @@ Let's show it on a simple example.
     ax3.plot(x1, y, 'o', xi1, yi1_n, '-')
     ax4.plot(x2, y, 'o', xi2, yi2_n, '-')
 
+    ax1.set_title('normalizedsmooth=False')
+    ax2.set_title('normalizedsmooth=False')
+    ax3.set_title('normalizedsmooth=True')
+    ax4.set_title('normalizedsmooth=True')
+
 
 Computing Spline Without Evaluating
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -408,6 +410,9 @@ The example for univariate data:
     ax1.plot(x, y, 'o', xi1, yi1, '.-')
     ax2.plot(x, y, 'o', xi2, yi2, '.-')
 
+    ax1.set_title('20 evaluated points')
+    ax2.set_title('50 evaluated points')
+
 
 .. _tutorial-analysis:
 
diff --git a/poetry.lock b/poetry.lock
diff --git a/pyproject.toml b/pyproject.toml
