migrate to sphinx-immaterial, various docs additions

README.rst

@@ -96,6 +96,14 @@ Notes
   (i.e. attribute access speed and *some* memory savings).
   However, in most cases this is unintentional.
   ``slotscheck`` allows you to ignore specific cases.
+- Because ``slotscheck`` imports your code in arbitrary order,
+  it can—in rare cases—result in confusing and randomly-occurring import errors
+  in third-party libraries.
+  In such a case, it is recommended to omit modules such as your tests
+  and mypy plugins from the slotscheck run.
+  See `here <https://github.com/ariebovenberg/slotscheck/issues/178>`_.
+  Alternatively, you can use ``PYTHONHASHSEED=<any value>`` to make the import order deterministic.
+  A solution to this problem is being worked on in `this issue <https://github.com/ariebovenberg/slotscheck/issues/270>`_.
 
 Installation
 ------------

docs/advanced.rst

@@ -7,13 +7,23 @@ Pre-commit hook
 You can run ``slotscheck`` as a pre-commit hook.
 Use the following configuration:
 
+.. attention::
+
+   Although slotscheck supports pre-commit, it is not recommended to use it.
+   Use ``tox`` or a similar tool instead.
+
+   Why? Slotscheck needs to import your code, so it needs the same
+   dependencies. Pre-commit isn't meant for this use case.
+   Configuring slotscheck to work with pre-commit is possible, but it's
+   error-prone since you need to make sure the dependencies in the pre-commit
+   container match the dependencies in your project.
+
 .. warning::
 
    Slotscheck imports files to check them.
    Be sure to specify ``exclude``
    to prevent slotscheck from importing scripts unintentionally.
 
-
 .. code-block:: yaml
 
    repos:
@@ -28,7 +38,7 @@ Use the following configuration:
        # Below is what you need to add if you're code isn't importable
        # from the project root, in a "src" directory:
        #
-       # entry: env PYTHONPATH=src slotscheck --verbose
+       # entry: cd src && python -m slotscheck --verbose
 
        # Add files you don't want slotscheck to import.
        # The example below ensures slotscheck will only run on

docs/conf.py

@@ -32,6 +32,7 @@
     "sphinx.ext.napoleon",
     "sphinx.ext.intersphinx",
     "sphinx.ext.viewcode",
+    "sphinx_immaterial",
     "sphinx_click",
 ]
 
@@ -63,37 +64,52 @@
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = "sphinx_material"
+html_theme = "sphinx_immaterial"
 
 # html_static_path = ['_static']
 # highlight_language = "python3"
 
 # Material theme options (see theme.conf for more information)
 html_theme_options = {
-    "nav_title": "🎰 Slotscheck",
-    # Set the color and the accent color
-    "color_primary": "red",
-    "color_accent": "light-red",
     # Set the repo location to get a badge with stats
     "repo_url": "https://github.com/ariebovenberg/slotscheck/",
-    "repo_name": "slotscheck",
-    # Visible levels of the global TOC; -1 means unlimited
-    "globaltoc_depth": 3,
-    # If False, expand all TOC entries
+    "repo_name": "🎰 Slotscheck",
     "globaltoc_collapse": False,
-    # If True, show hidden TOC entries
     "globaltoc_includehidden": False,
+
+    "palette": [
+        {
+            "media": "(prefers-color-scheme: light)",
+            "scheme": "default",
+            "primary": "red",
+            "accent": "orange",
+            "toggle": {
+                "icon": "material/weather-night",
+                "name": "Switch to dark mode",
+            },
+        },
+        {
+            "media": "(prefers-color-scheme: dark)",
+            "scheme": "slate",
+            "primary": "red",
+            "accent": "orange",
+            "toggle": {
+                "icon": "material/weather-sunny",
+                "name": "Switch to light mode",
+            },
+        },
+    ],
 }
 
 
-html_sidebars = {
-    "**": [
-        "logo-text.html",
-        "globaltoc.html",
-        "localtoc.html",
-        "searchbox.html",
-    ]
-}
+# html_sidebars = {
+#     "**": [
+#         "logo-text.html",
+#         "globaltoc.html",
+#         "localtoc.html",
+#         "searchbox.html",
+#     ]
+# }
 
 
 # Example configuration for intersphinx: refer to the Python standard library.

docs/requirements.txt

@@ -1,3 +1,3 @@
-sphinx~=7.2.6
-sphinx-material~=0.0.36
+sphinx>8,<9
+sphinx-immaterial>=0.12.4,<0.13
 sphinx-click~=6.0.0