STYLE: lint the documentation with Doc8 (#1150)

Fix #1139

.pre-commit-config.yaml

@@ -5,7 +5,7 @@ default_language_version:
 
 repos:
   - repo: https://github.com/pre-commit/mirrors-prettier
-    rev: v3.0.0-alpha.4
+    rev: v2.7.1
     hooks:
       - id: prettier
         # Exclude the HTML, since it doesn't understand Jinja2
@@ -43,3 +43,8 @@ repos:
     hooks:
       - id: djlint-jinja
         types_or: ["html"]
+
+  - repo: https://github.com/PyCQA/doc8
+    rev: v1.1.1
+    hooks:
+      - id: doc8

docs/examples/kitchen-sink/blocks.rst

@@ -238,10 +238,10 @@ With line numbers
             "This is an intentionally very long line because I want to make sure that we are handling scrollable code blocks correctly."
         )
 
-With ``none`` highlighting
-~~~~~~~~~~~~~~~~~~~~~~~~~~
+Without highlighting
+~~~~~~~~~~~~~~~~~~~~
 
-.. code-block:: none
+.. code-block:: text
 
     # Taken from https://en.wikipedia.org/wiki/Pseudocode#Example
     algorithm ford-fulkerson is

docs/user_guide/install.rst

@@ -46,7 +46,7 @@ install it from the git repo:
 
 or in a conda environment yml file, you can add:
 
-.. code:: none
+.. code:: yaml
 
     - pip:
       - git+https://github.com/pydata/pydata-sphinx-theme.git@main

pyproject.toml

@@ -82,3 +82,6 @@ dev = [
 
 [project.entry-points]
 "sphinx.html_themes" = { pydata_sphinx_theme = "pydata_sphinx_theme" }
+
+[tool.doc8]
+ignore = ["D001"] # we follow a 1 line = 1 paragraph style

src/pydata_sphinx_theme/assets/scripts/bootstrap.js

@@ -14,7 +14,7 @@ import "../styles/bootstrap.scss";
  */
 function TriggerTooltip() {
   var tooltipTriggerList = [].slice.call(
-    document.querySelectorAll('[data-bs-toggle="tooltip"]'),
+    document.querySelectorAll('[data-bs-toggle="tooltip"]')
   );
   tooltipTriggerList.map(function (tooltipTriggerEl) {
     return new Tooltip(tooltipTriggerEl, { delay: { show: 500, hide: 100 } });

src/pydata_sphinx_theme/assets/scripts/pydata-sphinx-theme.js

@@ -132,7 +132,7 @@ function scrollToActive() {
   // Inspired on source of revealjs.com
   let storedScrollTop = parseInt(
     sessionStorage.getItem("sidebar-scroll-top"),
-    10,
+    10
   );
 
   if (!isNaN(storedScrollTop)) {
@@ -184,7 +184,7 @@ var findSearchInput = () => {
     } else {
       // must be at least one persistent form, use the first persistent one
       form = document.querySelector(
-        "div:not(.search-button__search-container) > form.bd-search",
+        "div:not(.search-button__search-container) > form.bd-search"
       );
     }
     return form.querySelector("input");
@@ -235,7 +235,7 @@ var addEventListenerForSearchKeyboard = () => {
         toggleSearchField();
       }
     },
-    true,
+    true
   );
 };
 
@@ -247,7 +247,7 @@ var changeSearchShortcutKey = () => {
   var isMac = window.navigator.platform.toUpperCase().indexOf("MAC") >= 0;
   if (isMac) {
     forms.forEach(
-      (f) => (f.querySelector("kbd.kbd-shortcut__modifier").innerText = "⌘"),
+      (f) => (f.querySelector("kbd.kbd-shortcut__modifier").innerText = "⌘")
     );
   }
 };
@@ -331,7 +331,7 @@ if (themeSwitchBtns) {
         const node = document.createElement("a");
         node.setAttribute(
           "class",
-          "list-group-item list-group-item-action py-1",
+          "list-group-item list-group-item-action py-1"
         );
         node.setAttribute("href", `${entry.url}${currentFilePath}`);
         node.appendChild(span);

src/pydata_sphinx_theme/assets/styles/content/_api.scss

@@ -111,9 +111,7 @@ span.highlighted {
 
 // the API selector
 // from https://github.com/pradyunsg/furo/blob/main/src/furo/assets/styles/content/_api.sass#L6)
-dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.glossary):not(
-    .simple
-  ) {
+dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.glossary):not(.simple) {
   dd {
     margin-left: 2rem;