Chores: Update workflows, docs, and VSCode settings

Signed-off-by: Brian Warner <[email protected]>

.github/workflows/pre-release.yml

@@ -9,10 +9,6 @@ on:
       - '**'
       - '!main'
 
-permissions:
-  contents: write
-  pull-requests: write
-
 jobs:
   test:
     name: Test Python versions
@@ -29,7 +25,7 @@ jobs:
     - name: Install dependencies
       run: |
         python -m pip install --upgrade pip
-        python -m pip install flake8 pytest
+        python -m pip install flake8 pytest pytest-pretty
     - name: Lint with flake8
       run: |
         # stop the build if there are Python syntax errors or undefined names
@@ -40,26 +36,33 @@ jobs:
       run: |
         pytest
   build:
-    name: Build and generate documentation
+    name: Regenerate documentation
     needs: test
     runs-on: ubuntu-latest
+    permissions:
+      contents: write
     steps:
     - uses: actions/checkout@v4
     - name: Set up Python
       uses: actions/setup-python@v5
       with:
-        python-version: '3.x'
+        python-version: '3.12'
     - name: Install dependencies
       run: |
         python -m pip install --upgrade pip
-        python -m pip install build setuptools setuptools-scm sphinx sphinx_rtd_theme myst_parser
+        python -m pip install -r requirements-dev.txt
     - name: Build the packages
       run: |
         python -m build
     - name: Generate documentation
       run: |
         sphinx-build -b html docsrc docs -E -d "docsrc/_doctrees"
+    - name: Check if there are any changes
+      id: verify_diff
+      run: |
+        git diff --quiet . || echo "changed=true" >> $GITHUB_OUTPUT
     - name: Commit and push the new documentation
+      if: steps.verify_diff.outputs.changed == 'true'
       run: |
         git config user.name "Brian Warner"
         git config user.email [email protected]

.github/workflows/release.yml

@@ -1,4 +1,4 @@
-name: Test, build, generate docs, and publish to PyPI
+name: Test and publish to PyPI
 
 on:
   push:
@@ -21,7 +21,7 @@ jobs:
     - name: Install dependencies
       run: |
         python -m pip install --upgrade pip
-        python -m pip install flake8 pytest
+        python -m pip install flake8 pytest pytest-pretty
     - name: Lint with flake8
       run: |
         # stop the build if there are Python syntax errors or undefined names
@@ -32,35 +32,23 @@ jobs:
       run: |
         pytest
   pypi-publish:
-    name: Upload release to PyPI and update documentation
+    name: Upload release to PyPI
     needs: test
     runs-on: ubuntu-latest
-    environment: release
     permissions:
       id-token: write
     steps:
     - uses: actions/checkout@v4
     - name: Set up Python
       uses: actions/setup-python@v5
       with:
-        python-version: '3.x'
+        python-version: '3.12'
     - name: Install dependencies
       run: |
         python -m pip install --upgrade pip
-        python -m pip install build setuptools setuptools-scm sphinx sphinx_rtd_theme myst_parser
+        python -m pip install -r requirements-dev.txt
     - name: Build the packages
       run: |
         python -m build
     - name: Publish package distributions to PyPI
       uses: pypa/gh-action-pypi-publish@release/v1
-    - name: Generate documentation with latest version
-      run: |
-        sphinx-build -b html docsrc docs -E -d "docsrc/_doctrees"
-    - name: Commit and push the new documentation
-      if: steps.verify_diff.outputs.changed == 'true'
-      run: |
-        git config user.name "Brian Warner"
-        git config user.email [email protected]
-        git add docs
-        git commit -m "Rebuild the documentation" || exit 0
-        git push

.vscode/settings.json

@@ -1,6 +1,7 @@
 {
     "flake8.args": [
-        "--max-line-length=100"
+        "--max-line-length=100",
+        "--ignore=E203,W503",
     ],
     "flake8.ignorePatterns": [
         ".venv/*"
@@ -9,4 +10,5 @@
     "python.terminal.activateEnvInCurrentTerminal": true,
     "python.createEnvironment.contentButton": "show",
     "editor.formatOnSave": true,
+    "makefile.configureOnOpen": false,
 }

Makefile

@@ -17,3 +17,4 @@ build: clean test
 
 html: build
 	sphinx-build -b html docsrc docs -E -d "docsrc/_doctrees"
+	touch docs/.nojekyll

docs/.buildinfo

@@ -1,4 +1,4 @@
 # Sphinx build info version 1
-# This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
-config: cfee92e6764fd6783006a9379d7eb90c
+# This file records the configuration used when building these files. When it is not found, a full rebuild will be done.
+config: 84312769acdb3225cceb4714f4036a2f
 tags: 645f666f9bcd5a90fca523b33c5a78b7

docs/.buildinfo.bak

@@ -0,0 +1,4 @@
+# Sphinx build info version 1
+# This file records the configuration used when building these files. When it is not found, a full rebuild will be done.
+config: c275350ed3fba61546b0b0ef51753182
+tags: 645f666f9bcd5a90fca523b33c5a78b7

docs/_modules/index.html

@@ -5,15 +5,15 @@
 <head>
   <meta charset="utf-8" />
   <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-  <title>Overview: module code &mdash; talkGooder 0.0.post1.dev1+ge624e3d documentation</title>
+  <title>Overview: module code &mdash; talkGooder 0.0.post1.dev1+gbbb2af3 documentation</title>
       <link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=80d5e7a1" />
-      <link rel="stylesheet" type="text/css" href="../_static/css/theme.css?v=7ab3649f" />
+      <link rel="stylesheet" type="text/css" href="../_static/css/theme.css?v=e59714d7" />
 
 
       <script src="../_static/jquery.js?v=5d32c60e"></script>
       <script src="../_static/_sphinx_javascript_frameworks_compat.js?v=2cd50e6c"></script>
-      <script src="../_static/documentation_options.js?v=3c956434"></script>
-      <script src="../_static/doctools.js?v=9a2dae69"></script>
+      <script src="../_static/documentation_options.js?v=435997b2"></script>
+      <script src="../_static/doctools.js?v=9bcbadda"></script>
       <script src="../_static/sphinx_highlight.js?v=dc90522c"></script>
     <script src="../_static/js/theme.js"></script>
     <link rel="index" title="Index" href="../genindex.html" />

docs/_modules/talkgooder.html

@@ -5,15 +5,15 @@
 <head>
   <meta charset="utf-8" />
   <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-  <title>talkgooder &mdash; talkGooder 0.0.post1.dev1+ge624e3d documentation</title>
+  <title>talkgooder &mdash; talkGooder 0.0.post1.dev1+gbbb2af3 documentation</title>
       <link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=80d5e7a1" />
-      <link rel="stylesheet" type="text/css" href="../_static/css/theme.css?v=7ab3649f" />
+      <link rel="stylesheet" type="text/css" href="../_static/css/theme.css?v=e59714d7" />
 
 
       <script src="../_static/jquery.js?v=5d32c60e"></script>
       <script src="../_static/_sphinx_javascript_frameworks_compat.js?v=2cd50e6c"></script>
-      <script src="../_static/documentation_options.js?v=3c956434"></script>
-      <script src="../_static/doctools.js?v=9a2dae69"></script>
+      <script src="../_static/documentation_options.js?v=435997b2"></script>
+      <script src="../_static/doctools.js?v=9bcbadda"></script>
       <script src="../_static/sphinx_highlight.js?v=dc90522c"></script>
     <script src="../_static/js/theme.js"></script>
     <link rel="index" title="Index" href="../genindex.html" />

docs/_static/basic.css

@@ -1,12 +1,5 @@
 /*
- * basic.css
- * ~~~~~~~~~
- *
  * Sphinx stylesheet -- basic theme.
- *
- * :copyright: Copyright 2007-2024 by the Sphinx team, see AUTHORS.
- * :license: BSD, see LICENSE for details.
- *
  */
 
 /* -- main layout ----------------------------------------------------------- */
@@ -115,15 +108,11 @@ img {
 /* -- search page ----------------------------------------------------------- */
 
 ul.search {
-    margin: 10px 0 0 20px;
-    padding: 0;
+    margin-top: 10px;
 }
 
 ul.search li {
-    padding: 5px 0 5px 20px;
-    background-image: url(file.png);
-    background-repeat: no-repeat;
-    background-position: 0 7px;
+    padding: 5px 0;
 }
 
 ul.search li a {

docs/_static/doctools.js

@@ -1,12 +1,5 @@
 /*
- * doctools.js
- * ~~~~~~~~~~~
- *
  * Base JavaScript utilities for all Sphinx HTML documentation.
- *
- * :copyright: Copyright 2007-2024 by the Sphinx team, see AUTHORS.
- * :license: BSD, see LICENSE for details.
- *
  */
 "use strict";
 

docs/_static/documentation_options.js

@@ -1,5 +1,5 @@
 const DOCUMENTATION_OPTIONS = {
-    VERSION: '0.0.post1.dev1+ge624e3d',
+    VERSION: '0.0.post1.dev1+gbbb2af3',
     LANGUAGE: 'en',
     COLLAPSE_INDEX: false,
     BUILDER: 'html',

docs/_static/js/versions.js

@@ -1,17 +1,21 @@
 const themeFlyoutDisplay = "hidden";
-const themeVersionSelector = "True";
-const themeLanguageSelector = "True";
+const themeVersionSelector = true;
+const themeLanguageSelector = true;
 
 if (themeFlyoutDisplay === "attached") {
   function renderLanguages(config) {
     if (!config.projects.translations.length) {
       return "";
     }
 
+    // Insert the current language to the options on the selector
+    let languages = config.projects.translations.concat(config.projects.current);
+    languages = languages.sort((a, b) => a.language.name.localeCompare(b.language.name));
+
     const languagesHTML = `
       <dl>
         <dt>Languages</dt>
-        ${config.projects.translations
+        ${languages
           .map(
             (translation) => `
         <dd ${translation.slug == config.projects.current.slug ? 'class="rtd-current-item"' : ""}>

docs/_static/language_data.js

@@ -1,13 +1,6 @@
 /*
- * language_data.js
- * ~~~~~~~~~~~~~~~~
- *
  * This script contains the language-specific data used by searchtools.js,
  * namely the list of stopwords, stemmer, scorer and splitter.
- *
- * :copyright: Copyright 2007-2024 by the Sphinx team, see AUTHORS.
- * :license: BSD, see LICENSE for details.
- *
  */
 
 var stopwords = ["a", "and", "are", "as", "at", "be", "but", "by", "for", "if", "in", "into", "is", "it", "near", "no", "not", "of", "on", "or", "such", "that", "the", "their", "then", "there", "these", "they", "this", "to", "was", "will", "with"];

docs/_static/searchtools.js

@@ -1,12 +1,5 @@
 /*
- * searchtools.js
- * ~~~~~~~~~~~~~~~~
- *
  * Sphinx JavaScript utilities for the full-text search.
- *
- * :copyright: Copyright 2007-2024 by the Sphinx team, see AUTHORS.
- * :license: BSD, see LICENSE for details.
- *
  */
 "use strict";
 
@@ -20,7 +13,7 @@ if (typeof Scorer === "undefined") {
     // and returns the new score.
     /*
     score: result => {
-      const [docname, title, anchor, descr, score, filename] = result
+      const [docname, title, anchor, descr, score, filename, kind] = result
       return score
     },
     */
@@ -47,6 +40,14 @@ if (typeof Scorer === "undefined") {
   };
 }
 
+// Global search result kind enum, used by themes to style search results.
+class SearchResultKind {
+    static get index() { return  "index"; }
+    static get object() { return "object"; }
+    static get text() { return "text"; }
+    static get title() { return "title"; }
+}
+
 const _removeChildren = (element) => {
   while (element && element.lastChild) element.removeChild(element.lastChild);
 };
@@ -64,9 +65,13 @@ const _displayItem = (item, searchTerms, highlightTerms) => {
   const showSearchSummary = DOCUMENTATION_OPTIONS.SHOW_SEARCH_SUMMARY;
   const contentRoot = document.documentElement.dataset.content_root;
 
-  const [docName, title, anchor, descr, score, _filename] = item;
+  const [docName, title, anchor, descr, score, _filename, kind] = item;
 
   let listItem = document.createElement("li");
+  // Add a class representing the item's type:
+  // can be used by a theme's CSS selector for styling
+  // See SearchResultKind for the class names.
+  listItem.classList.add(`kind-${kind}`);
   let requestUrl;
   let linkUrl;
   if (docBuilder === "dirhtml") {
@@ -115,8 +120,10 @@ const _finishSearch = (resultCount) => {
       "Your search did not match any documents. Please make sure that all words are spelled correctly and that you've selected enough categories."
     );
   else
-    Search.status.innerText = _(
-      "Search finished, found ${resultCount} page(s) matching the search query."
+    Search.status.innerText = Documentation.ngettext(
+      "Search finished, found one page matching the search query.",
+      "Search finished, found ${resultCount} pages matching the search query.",
+      resultCount,
     ).replace('${resultCount}', resultCount);
 };
 const _displayNextItem = (
@@ -138,7 +145,7 @@ const _displayNextItem = (
   else _finishSearch(resultCount);
 };
 // Helper function used by query() to order search results.
-// Each input is an array of [docname, title, anchor, descr, score, filename].
+// Each input is an array of [docname, title, anchor, descr, score, filename, kind].
 // Order the results by score (in opposite order of appearance, since the
 // `_displayNextItem` function uses pop() to retrieve items) and then alphabetically.
 const _orderResultsByScoreThenName = (a, b) => {
@@ -248,6 +255,7 @@ const Search = {
     searchSummary.classList.add("search-summary");
     searchSummary.innerText = "";
     const searchList = document.createElement("ul");
+    searchList.setAttribute("role", "list");
     searchList.classList.add("search");
 
     const out = document.getElementById("search-results");
@@ -318,7 +326,7 @@ const Search = {
     const indexEntries = Search._index.indexentries;
 
     // Collect multiple result groups to be sorted separately and then ordered.
-    // Each is an array of [docname, title, anchor, descr, score, filename].
+    // Each is an array of [docname, title, anchor, descr, score, filename, kind].
     const normalResults = [];
     const nonMainIndexResults = [];
 
@@ -337,6 +345,7 @@ const Search = {
             null,
             score + boost,
             filenames[file],
+            SearchResultKind.title,
           ]);
         }
       }
@@ -354,6 +363,7 @@ const Search = {
             null,
             score,
             filenames[file],
+            SearchResultKind.index,
           ];
           if (isMain) {
             normalResults.push(result);
@@ -475,6 +485,7 @@ const Search = {
         descr,
         score,
         filenames[match[0]],
+        SearchResultKind.object,
       ]);
     };
     Object.keys(objects).forEach((prefix) =>
@@ -585,6 +596,7 @@ const Search = {
         null,
         score,
         filenames[file],
+        SearchResultKind.text,
       ]);
     }
     return results;