sphinx material

.github/workflows/build-docs.yml

@@ -40,7 +40,7 @@ jobs:
         run: timeout 10s poetry run pip --version || rm -rf .venv
 
       - name: Install dependencies
-        run: poetry install
+        run: poetry install -E docs
 
       - name: Build documentation
         run: |

.readthedocs.yaml

@@ -10,7 +10,9 @@ sphinx:
 formats: all
 
 python:
-  version: 3.7
+  version: 3.8
   install:
     - method: pip
       path: .
+      extra_requirements:
+        - docs

docs/conf.py

@@ -37,6 +37,7 @@
     "sphinx.ext.intersphinx",
     "sphinx.ext.coverage",
     "sphinx.ext.viewcode",
+    "sphinx_immaterial",
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -53,9 +54,55 @@
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = "sphinx_rtd_theme"
+html_theme = "sphinx_immaterial"
 
 # 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 = []
+
+# Set link name generated in the top bar.
+html_title = "openapi-core"
+
+# Material theme options (see theme.conf for more information)
+html_theme_options = {
+    # Set you GA account ID to enable tracking
+    # 'google_analytics_account': 'UA-XXXXX',
+    # Specify a base_url used to generate sitemap.xml. If not
+    # specified, then no sitemap will be built.
+    #'base_url': 'https://project.github.io/project',
+    # Set the color and the accent color
+    # Set the repo location to get a badge with stats
+    "repo_url": "https://github.com/p1c2u/openapi-core/",
+    "repo_name": "openapi-core",
+    "repo_type": "github",
+    "icon": {
+        "repo": "fontawesome/brands/github-alt",
+        "edit": "material/file-edit-outline",
+    },
+    "palette": [
+        {
+            "media": "(prefers-color-scheme: dark)",
+            "scheme": "slate",
+            "primary": "lime",
+            "accent": "amber",
+            "scheme": "slate",
+            "toggle": {
+                "icon": "material/toggle-switch",
+                "name": "Switch to light mode",
+            },
+        },
+        {
+            "media": "(prefers-color-scheme: light)",
+            "scheme": "default",
+            "primary": "lime",
+            "accent": "amber",
+            "toggle": {
+                "icon": "material/toggle-switch-off-outline",
+                "name": "Switch to dark mode",
+            },
+        },
+    ],
+    # If False, expand all TOC entries
+    "globaltoc_collapse": False,
+}

pyproject.toml

@@ -66,8 +66,11 @@ werkzeug = "*"
 typing-extensions = "^4.3.0"
 jsonschema-spec = "^0.1.1"
 backports-cached-property = {version = "^1.0.2", python = "<3.8" }
+sphinx = {version = "^5.3.0", optional = true}
+sphinx-immaterial = {version = "^0.11.0", optional = true}
 
 [tool.poetry.extras]
+docs = ["sphinx", "sphinx-immaterial"]
 django = ["django"]
 falcon = ["falcon"]
 flask = ["flask"]
@@ -86,14 +89,16 @@ pytest = "^7"
 pytest-flake8 = "*"
 pytest-cov = "*"
 responses = "*"
-sphinx = "^5.3.0"
-sphinx-rtd-theme = "^1.2.0"
 strict-rfc3339 = "^0.7"
 webob = "*"
 mypy = "^1.0"
 starlette = "^0.25.0"
 httpx = "^0.23.3"
 
+[tool.poetry.group.docs.dependencies]
+sphinx = "^5.3.0"
+sphinx-immaterial = "^0.11.0"
+
 [tool.pytest.ini_options]
 addopts = """
 --capture=no