Merge pull request #271 from ariebovenberg/docs-fixes

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,6 +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:
        #
+       # NOTE: This won't work on Windows though.
        # entry: env PYTHONPATH=src slotscheck --verbose
 
        # Add files you don't want slotscheck to import.

docs/conf.py

@@ -1,12 +1,3 @@
-# -*- coding: utf-8 -*-
-#
-# Configuration file for the Sphinx documentation builder.
-#
-# This file does only contain a selection of the most common options. For a
-# full list see the documentation:
-# http://www.sphinx-doc.org/en/master/config
-
-
 # -- Project information -----------------------------------------------------
 import importlib.metadata
 
@@ -19,14 +10,6 @@
 release = metadata["Version"]
 
 # -- General configuration ---------------------------------------------------
-
-# If your documentation needs a minimal Sphinx version, state it here.
-#
-# needs_sphinx = '1.0'
-
-# 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.napoleon",
@@ -35,68 +18,26 @@
     "sphinx_click",
 ]
 
-# 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"
 
 # The master toctree document.
 master_doc = "index"
-
-# 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"]
 
-# The name of the Pygments (syntax highlighting) style to use.
-pygments_style = "tango"
-
-autodoc_member_order = "bysource"
-
 
 # -- 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 = "sphinx_material"
-
-# 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
-    "globaltoc_collapse": False,
-    # If True, show hidden TOC entries
-    "globaltoc_includehidden": False,
-}
-
-
-html_sidebars = {
-    "**": [
-        "logo-text.html",
-        "globaltoc.html",
-        "localtoc.html",
-        "searchbox.html",
-    ]
-}
+html_theme = "furo"
+pygments_style = "tango"
+highlight_language = "python3"
+pygments_style = "default"
+pygments_dark_style = "lightbulb"
+autodoc_member_order = "bysource"
 
+toc_object_entries_show_parents = "hide"
 
-# Example configuration for intersphinx: refer to the Python standard library.
 intersphinx_mapping = {
     "python": ("https://docs.python.org/3", None),
 }

docs/requirements.txt

@@ -1,3 +1,3 @@
-sphinx~=7.2.6
-sphinx-material~=0.0.36
+sphinx>8,<9
+furo>=2024.8.6,<2025
 sphinx-click~=6.0.0