Improved documentation theme and layout (#29)

Alexboiboi · pre-commit-ci[bot] · web-flow · commit 6877a55795a9 · 2025-10-30T21:49:06.000+01:00
* move to pydata_sphinx_theme

* feat: add full-width CSS and examples documentation

* style: pre-commit fixes

* update changelog

* style: pre-commit fixes

---------

Co-authored-by: pre-commit-ci[bot] &lt;66853113+pre-commit-ci[bot]@users.noreply.github.com&gt;
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,28 +1,91 @@
-# Unreleased
+# Changelog
 
-# 0.3.0
+All notable changes to this project will be documented in this file.
 
-- improved interface for chi input
-- FE tests for anisotropic chi and negative chi
-- Improve internals
-- anisotropic susceptibilities are now allowed.
-- Improve susceptibility input possibilities:
-  - give susceptibility to parent collection
-  - if susceptibility input is scalar, isotropic susceptibility is assumed, if
-    it is a 3-vector it can be anisotropic
-- Various tests included of interface and computation, isotropic and anisotropic
-  tests confirm computation
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-# 0.2.1a0
+## [Unreleased]
 
-- Fix null polarization for rotated objects
+## [0.3.1] - 2025-10-30
+
+### Fixed
+
+- Fixed susceptibility tree traversal
+  ([#26](https://github.com/magpylib/magpylib-material-response/pull/26),
+  [#28](https://github.com/magpylib/magpylib-material-response/pull/28))
+
+### Changed
+
+- Improved clarity and error handling in `get_susceptibilities` function
+- Enhanced logging configuration
+- Refactored demag.py for better organization
+- Improved documentation theme and layout
+  ([#29](https://github.com/magpylib/magpylib-material-response/pull/29))
+  - Switched from Furo to PyData Sphinx theme
+  - Added custom CSS for full-width content and smaller sidebar
+  - Enhanced navigation and branding with Magpylib logo
+  - Reorganized examples section structure
+
+### Maintenance
+
+- Updated pre-commit hooks to latest versions
+  ([#21](https://github.com/magpylib/magpylib-material-response/pull/21))
+- Updated GitHub Actions dependencies
+  ([#24](https://github.com/magpylib/magpylib-material-response/pull/24))
+- Removed test PyPI repository URL from publish step
+  ([#27](https://github.com/magpylib/magpylib-material-response/pull/27))
+- Added VSCode settings for pytest configuration
+
+## [0.3.0] - 2024-10-16
+
+### Added
+
+- Support for anisotropic susceptibilities
+- FE tests for anisotropic and negative susceptibility values
+- Comprehensive tests for interface and computation validation
+- Susceptibility input to parent collections
+- Support for both scalar (isotropic) and 3-vector (anisotropic) susceptibility
+  inputs
+
+### Changed
+
+- Improved interface for susceptibility (chi) input
+- Enhanced susceptibility input possibilities:
+  - Scalar input now assumes isotropic susceptibility
+  - 3-vector input enables anisotropic susceptibility
+- Improved internal architecture and code organization
+
+### Fixed
+
+- Various computation fixes confirmed by isotropic and anisotropic tests
+
+## [0.2.1a0]
+
+### Fixed
+
+- Fixed null polarization for rotated objects
   ([#7](https://github.com/magpylib/magpylib-material-response/pull/7))
-- Fix docs not building
+- Fixed documentation build issues
   ([#6](https://github.com/magpylib/magpylib-material-response/pull/6))
 
-# 0.2.0a0
+## [0.2.0a0]
 
-- renaming xi->susceptibility
+### Changed
+
+- Renamed `xi` parameter to `susceptibility` for better clarity
   ([#5](https://github.com/magpylib/magpylib-material-response/pull/5))
-- update to magpylib v5
+- Updated to support magpylib v5
   ([#4](https://github.com/magpylib/magpylib-material-response/pull/4))
+
+[Unreleased]:
+  https://github.com/magpylib/magpylib-material-response/compare/v0.3.1...HEAD
+[0.3.1]:
+  https://github.com/magpylib/magpylib-material-response/compare/v0.3.0...v0.3.1
+[0.3.0]:
+  https://github.com/magpylib/magpylib-material-response/compare/v0.2.1a0...v0.3.0
+[0.2.1a0]:
+  https://github.com/magpylib/magpylib-material-response/compare/v0.2.0a0...v0.2.1a0
+[0.2.0a0]:
+  https://github.com/magpylib/magpylib-material-response/releases/tag/v0.2.0a0
diff --git a/docs/_static/fullwidth.css b/docs/_static/fullwidth.css
@@ -0,0 +1,24 @@
+/* PyData Sphinx Theme Full Width CSS - Simplest Approach */
+/* Apply full-width to all main containers */
+
+.bd-container,
+.bd-container__inner {
+  max-width: 100% !important;
+}
+
+.bd-main,
+.bd-content {
+  max-width: 100% !important;
+}
+
+.bd-article-container,
+.bd-article {
+  max-width: 100em !important;
+}
+
+/* Ensure notebook cells use full width */
+.cell,
+.cell_input,
+.cell_output {
+  max-width: 100% !important;
+}
diff --git a/docs/_static/images/magpylib_logo.png b/docs/_static/images/magpylib_logo.png
diff --git a/docs/conf.py b/docs/conf.py
@@ -28,24 +28,42 @@
     ".venv",
 ]
 
-html_theme = "furo"
+html_theme = "pydata_sphinx_theme"
 
 html_theme_options: dict[str, Any] = {
-    "footer_icons": [
+    # "announcement": announcement,
+    "logo": {
+        "text": "Magpylib-Material-Response",
+        "image_light": "_static/images/magpylib_logo.png",
+        "image_dark": "_static/images/magpylib_logo.png",
+    },
+    "header_links_before_dropdown": 4,
+    "show_version_warning_banner": True,
+    "navbar_align": "content",  # [left, content, right] For testing that the navbar items align properly
+    "navbar_center": ["navbar-nav"],
+    "check_switcher": True,
+    "icon_links": [
         {
             "name": "GitHub",
             "url": "https://github.com/magpylib/magpylib-material-response",
-            "html": """
-                <svg stroke="currentColor" fill="currentColor" stroke-width="0" viewBox="0 0 16 16">
-                    <path fill-rule="evenodd" d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0 0 16 8c0-4.42-3.58-8-8-8z"></path>
-                </svg>
-            """,
-            "class": "",
+            "icon": "https://img.shields.io/github/stars/magpylib/magpylib-material-response?style=social",
+            "type": "url",
         },
     ],
-    "source_repository": "https://github.com/magpylib/magpylib-material-response",
-    "source_branch": "main",
-    "source_directory": "docs/",
+    "navigation_with_keys": False,
+    "footer_start": ["copyright"],
+    "footer_end": [],
+    "use_edit_page_button": True,
+    "navigation_depth": 3,
+    "collapse_navigation": False,
+}
+
+html_context = {
+    # "github_url": "https://github.com", # or your GitHub Enterprise site
+    "github_user": "magpylib",
+    "github_repo": "magpylib-material-response",
+    "github_version": "main",
+    "doc_path": "docs/",
 }
 
 myst_enable_extensions = [
@@ -74,3 +92,11 @@
 always_document_param_types = True
 
 suppress_warnings = ["mystnb.unknown_mime_type"]
+
+html_js_files = [
+    "https://cdnjs.cloudflare.com/ajax/libs/require.js/2.3.4/require.min.js",
+]
+
+# Static files (CSS/JS)
+html_static_path = ["_static"]
+html_css_files = ["fullwidth.css"]
diff --git a/docs/examples/index.md b/docs/examples/index.md
@@ -0,0 +1,11 @@
+# Examples
+
+This section contains examples demonstrating the use of
+Magpylib-Material-Response.
+
+```{toctree}
+:maxdepth: 1
+:glob:
+
+*
+```
diff --git a/docs/index.md b/docs/index.md
@@ -1,4 +1,4 @@
-# magpylib-material-response
+# Documentation
 
 ```{include} ../README.md
 :start-after: <!-- SPHINX-START -->
@@ -8,14 +8,8 @@
 :caption: CONTENT
 :glob: true
 :maxdepth: 2
-```
-
-```{toctree}
-:caption: EXAMPLES
-:glob: true
-:maxdepth: 2
 
-examples/*
+examples/index
 ```
 
 ## Indices and tables
diff --git a/pyproject.toml b/pyproject.toml
@@ -42,12 +42,13 @@ dev = [
   "pytest-cov >=3",
 ]
 docs = [
+  "pydata-sphinx-theme",
   "sphinx>=7.0,<8.0",
   "myst_nb",
   "sphinx_copybutton",
   "sphinx_autodoc_typehints",
-  "furo>=2023.08.17",
   "pandas",
+  "plotly>=5.16,<6.0",
 ]
 
 [project.urls]

Original file line number	Diff line number	Diff line change
`@@ -42,12 +42,13 @@ dev = [`
`42`	`42`	`"pytest-cov >=3",`
`43`	`43`	`]`
`44`	`44`	`docs = [`
	`45`	`+ "pydata-sphinx-theme",`
`45`	`46`	`"sphinx>=7.0,<8.0",`
`46`	`47`	`"myst_nb",`
`47`	`48`	`"sphinx_copybutton",`
`48`	`49`	`"sphinx_autodoc_typehints",`
`49`		`- "furo>=2023.08.17",`
`50`	`50`	`"pandas",`
	`51`	`+ "plotly>=5.16,<6.0",`
`51`	`52`	`]`
`52`	`53`
`53`	`54`	`[project.urls]`