Update to Sphinx 7.0 & enable parallell builds (#891)

* chore: update sphinx 7 * feat: enable parallel builds * Fix RemoveSphinx8 warning * Bump sphinx multiversion * docs: update release notes * docs: Update CHANGELOG.md * docs: list upgrade guide * rm: poetry.lock * docs: update poetry lock * fix: warnings scylladb project * chore: run linter * chore: fix eol * fix: tests fix: tests fix: tests
scylladb · Oct 6, 2023 · e9cdcc8 · e9cdcc8
1 parent 7266c28
commit e9cdcc8
Show file tree

Hide file tree

Showing 46 changed files with 631 additions and 647 deletions.
diff --git a/.github/actions/amplify-enhanced/index.js b/.github/actions/amplify-enhanced/index.js
@@ -28,7 +28,7 @@ async function main() {
   try {
     const result = await octokit.request(
       `GET /repos/${request.owner}/${request.repo}/pulls/${github.context.issue.number}/files`,
-      request
+      request,
     );
     changedFiles = result.data;
   } catch (err) {
@@ -73,7 +73,7 @@ async function main() {
         owner: github.context.repo.owner,
         repo: github.context.repo.repo,
         comment_id: github.context.payload.comment.id,
-        body: `${bodyComment}\n\nFiles changed:\n${docFiles.join('')}`,
+        body: `${bodyComment}\n\nFiles changed:\n${docFiles.join("")}`,
       });
     } catch (err) {
       core.setFailed(`Comment failed with error ${err}`);
@@ -83,7 +83,7 @@ async function main() {
 
 const bodyComment = github.context.payload.comment.body;
 const amplifyComment = `${bodyComment}`.includes(
-  "This pull request is automatically being deployed by Amplify Hosting"
+  "This pull request is automatically being deployed by Amplify Hosting",
 );
 if (github.context.payload.issue.pull_request && amplifyComment) {
   main();

diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -1,5 +1,5 @@
 fail_fast: true
-
+exclude: ^(.github|src|sphinx_scylladb_theme/static)
 repos:
   - repo: local
     hooks:
@@ -10,35 +10,34 @@ repos:
         language: system
         pass_filenames: false
   - repo: https://github.com/psf/black
-    rev: 21.12b0
+    rev: 23.9.1
     hooks:
       - id: black
 
   - repo: https://github.com/pycqa/isort
-    rev: 5.10.1
+    rev: 5.12.0
     hooks:
       - id: isort
 
   - repo: https://github.com/pre-commit/mirrors-prettier
-    rev: v2.3.0
+    rev: v3.0.3
     hooks:
       - id: prettier
 
   - repo: https://github.com/rtts/djhtml
-    rev: v1.4.11
+    rev: 3.0.6
     hooks:
       - id: djhtml
 
   - repo: https://github.com/pycqa/flake8
-    rev: "4.0.1"
+    rev: "6.1.0"
     hooks:
       - id: flake8
 
   - repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v4.1.0
+    rev: v4.4.0
     hooks:
       - id: end-of-file-fixer
-        exclude: "sphinx_scylladb_theme/static"
       - id: trailing-whitespace
       - id: check-yaml
       - id: check-json
diff --git a/amplify.yml b/amplify.yml
@@ -9,7 +9,7 @@ applications:
       artifacts:
         baseDirectory: _build/dirhtml
         files:
-          - '**/*'
+          - "**/*"
       cache:
         paths: []
     appRoot: docs
diff --git a/docs/Makefile b/docs/Makefile
@@ -1,7 +1,7 @@
 # Global variables
 # You can set these variables from the command line.
 POETRY        = poetry
-SPHINXOPTS    =
+SPHINXOPTS    = -j auto
 SPHINXBUILD   = $(POETRY) run sphinx-build
 PAPER         =
 BUILDDIR      = _build

diff --git a/docs/_utils/pyproject_template.toml b/docs/_utils/pyproject_template.toml
@@ -5,15 +5,15 @@ version = "0.1.0"
 authors = ["ScyllaDB Documentation Contributors"]
 
 [tool.poetry.dependencies]
-python = "^3.7"
-pyyaml = "6.0"
+python = "^3.9"
+pyyaml = "6.0.1"
 pygments = "2.15.1"
-sphinx-scylladb-theme = "~1.5.1"
-myst-parser = "0.18.1"
+sphinx-scylladb-theme = "~1.6.1"
+myst-parser = "2.0.0"
 sphinx-autobuild = "2021.3.14"
-Sphinx = "4.3.2"
-sphinx-multiversion-scylla = "~0.2.11"
-sphinx-sitemap = "2.5.0"
+Sphinx = "7.2.6"
+sphinx-multiversion-scylla = "^0.3.1"
+sphinx-sitemap = "2.5.1"
 redirects_cli ="~0.1.3"
 
 [build-system]

diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -12,7 +12,15 @@
 
 # Builds documentation for the following tags and branches.
 TAGS = []
-BRANCHES = ["branch-1.5", "branch-1.4", "branch-1.3", "branch-1.2", "branch-1.1", "branch-1.0", "master"]
+BRANCHES = [
+    "branch-1.5",
+    "branch-1.4",
+    "branch-1.3",
+    "branch-1.2",
+    "branch-1.1",
+    "branch-1.0",
+    "master",
+]
 # Sets the latest version.
 LATEST_VERSION = "branch-1.5"
 # Set which versions are not released yet.
@@ -46,7 +54,7 @@
 # General information about the project.
 project = "ScyllaDB Sphinx Theme"
 copyright = str(date.today().year) + ", ScyllaDB. All rights reserved."
-author = u"ScyllaDB Project Contributors"
+author = "ScyllaDB Project Contributors"
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
@@ -104,7 +112,7 @@
 html_theme_options = {
     "conf_py_path": "docs/source/",
     "hide_edit_this_page_button": "false",
-    "hide_feedback_buttons": 'false',
+    "hide_feedback_buttons": "false",
     "github_issues_repository": "scylladb/sphinx-scylladb-theme",
     "github_repository": "scylladb/sphinx-scylladb-theme",
     "site_description": "Sphinx Theme for ScyllaDB projects.",
@@ -130,6 +138,7 @@
 
 # -- Initialize Sphinx ----------------------------------------------
 
+
 def setup(sphinx):
     warnings.filterwarnings(
         action="ignore",

diff --git a/docs/source/configuration/index.rst b/docs/source/configuration/index.rst
@@ -22,4 +22,4 @@ Configuration
   * :doc:`Multiversion options <multiversion>` - Configuration options for the multiversion extension.
   * :doc:`Markdown support <markdown>` - Extension to write documentation with Markdown.
   * :doc:`Redirects support <redirects>` - Extension to create redirects.
-  * :doc:`Search support <search>` - Service to index content that is searchable across all sites.
+  * :doc:`Search support <search>` - Service to index content that is searchable across all sites.
diff --git a/docs/source/configuration/markdown.md b/docs/source/configuration/markdown.md
@@ -12,25 +12,24 @@ To install MyST:
 
 1. Install the extension:
 
-    ```console
-    poetry add myst-parser
-    ```
+   ```console
+   poetry add myst-parser
+   ```
 
-2. Load the extension in the  `conf.py` configuration file:
+2. Load the extension in the `conf.py` configuration file:
 
-    ```python
-    extensions = ["myst_parser"]
-    ```
+   ```python
+   extensions = ["myst_parser"]
+   ```
 
-3. Add the following configuration in the  `conf.py` to enable the `colon_fence` extension:
+3. Add the following configuration in the `conf.py` to enable the `colon_fence` extension:
 
-    ```python
-    myst_enable_extensions = ["colon_fence"]
-    ```
+   ```python
+   myst_enable_extensions = ["colon_fence"]
+   ```
 
 For more details, see the [MyST documentation](https://myst-parser.readthedocs.io/en/latest/intro.html#/).
 
-
 ### Usage
 
 MyST extends the [CommonMark syntax](https://spec.commonmark.org/) specification. For more details, see the [Authoring](https://myst-parser.readthedocs.io/en/latest/syntax/typography.html) section of the MyST documentation.
@@ -44,4 +43,3 @@ This extension is deprecated and will be removed in a future release. If you are
 :::
 
 See [recommonmark docs](https://recommonmark.readthedocs.io/en/latest/) for more details on how to install and use this parser.
-
diff --git a/docs/source/configuration/multiversion.rst b/docs/source/configuration/multiversion.rst
@@ -101,7 +101,7 @@ However, if you still need to preview the latest local changes with the multiver
 #. In the same file, add your current branch's name to the ``BRANCHES`` list and set it as the latest version. For example:
 
     .. code-block:: python
-        
+
         BRANCHES = ["my-local-branch"]
         LATEST_VERSION = "my-local-branch"
 
@@ -115,7 +115,7 @@ To preview production builds locally:
 #. Create a temporal folder and move to it:
 
     .. code-block:: console
-        
+
         mktemp
         cd <PATH_TO_TEMP_FOLDER>
 

diff --git a/docs/source/configuration/template.rst b/docs/source/configuration/template.rst
@@ -23,7 +23,7 @@ General configuration options.
     - Set to ``true`` to load ScyllaDB JS specific scripts, including Google Tag Manager, Expertrec, and Zendesk configuration.
   * - ``skip_warnings``
     - string
-    - 
+    -
     - List of custom warnings implemented by the theme to exclude, separated by commas. Available values are: ``document_has_underscores``.
 
 Example:
@@ -277,4 +277,4 @@ Configuration options for the like and dislike buttons shown at the bottom of th
 
   html_theme_options = {
       'hide_feedback_buttons': 'true',
-  }
+  }
diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -90,7 +90,7 @@
 .. raw:: html
 
   </div>
-  
+
 .. toctree::
   :hidden:
 

diff --git a/docs/source/upgrade/1-3-to-1-4.rst b/docs/source/upgrade/1-3-to-1-4.rst
@@ -26,7 +26,7 @@ Here are the main breaking changes between the 1.3 and 1.4 versions.
 #. Edit the ``docs/Makefile`` file and add the ``rm -f poetry.lock`` to the ``clean`` command:
 
     .. code-block::
-        
+
         # Clean commands
         .PHONY: clean
         clean:

diff --git a/docs/source/upgrade/1-4-to-1-5.rst b/docs/source/upgrade/1-4-to-1-5.rst
@@ -50,4 +50,4 @@ Here are the main breaking changes between the 1.4 and 1.5 versions.
         cd docs
         make preview
 
-#. Review and address any warnings that may arise in the terminal during the build process.
+#. Review and address any warnings that may arise in the terminal during the build process.
diff --git a/docs/source/upgrade/1-5-to-1-6.rst b/docs/source/upgrade/1-5-to-1-6.rst
@@ -0,0 +1,37 @@
+Migrating from 1.5 to 1.6
+=========================
+
+This guide explains how to upgrade the version of the ScyllaDB Sphinx Theme.
+
+How to check your current theme version
+---------------------------------------
+
+The theme version is displayed in the footer of the project's documentation site.
+
+.. image:: version.png
+
+If your project theme's version is **>=1.5**, follow this guide to get the latest version.
+
+Upgrade to version 1.6
+----------------------
+
+Here are the main breaking changes between the 1.4 and 1.5 versions.
+
+#. Update the following Python dependencies in ``docs/pyproject.toml``:
+
+    .. code-block::
+
+        sphinx-scylladb-theme = "~1.6.1"
+        pyyaml = "6.0.1"
+        Sphinx = "7.2.6"
+        sphinx-multiversion-scylla = "~0.3.1"
+        sphinx-sitemap = "2.5.1"
+
+#. Build the docs locally:
+
+    .. code-block:: console
+
+        cd docs
+        make preview
+
+#. Review and address any warnings that may arise in the terminal during the build process.
diff --git a/docs/source/upgrade/CHANGELOG.md b/docs/source/upgrade/CHANGELOG.md
@@ -5,6 +5,23 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## 1.6.1 - TBD 2023
+
+### Added
+
+- [#891](https://github.com/scylladb/sphinx-scylladb-theme/pull/891): We have introduced support for parallel builds to enhance performance and speed up the documentation builds.
+- [#890](https://github.com/scylladb/sphinx-scylladb-theme/pull/890): Support for repositories that use Git Large File Storage (LFS).
+
+### Updated
+
+- [#891](https://github.com/scylladb/sphinx-scylladb-theme/pull/891): Upgraded Sphinx to version 7.2.4. Additionally, we now require a minimum of Python 3.9 for compatibility.
+- [#867](https://github.com/scylladb/sphinx-scylladb-theme/pull/867): Updated the header link to point the latest open-source documentation site.
+- [#827](https://github.com/scylladb/sphinx-scylladb-theme/pull/827): Improved the documentation for building multiversioned docs locally.
+
+## Removed
+
+- [#867](https://github.com/scylladb/sphinx-scylladb-theme/pull/867): For Windows users: The theme drops Git Bash support in favor of WSL.
+
 ## 1.5.1 - 31 May 2023
 
 ### Added
@@ -38,7 +55,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
-- [#652](https://github.com/scylladb/sphinx-scylladb-theme/pull/652): The docs builds now raises a warning if a RST or MD file has underscores in the filename. 
+- [#652](https://github.com/scylladb/sphinx-scylladb-theme/pull/652): The docs builds now raises a warning if a RST or MD file has underscores in the filename.
 - [#696](https://github.com/scylladb/sphinx-scylladb-theme/pull/696): The announcement banner can be managed from Google Tag Manager.
 
 ### Fixed

diff --git a/docs/source/upgrade/index.rst b/docs/source/upgrade/index.rst
@@ -5,6 +5,7 @@ Upgrade guides
    :maxdepth: 2
    :hidden:
 
+   1-5-to-1-6
    1-4-to-1-5
    1-3-to-1-4
    1-2-to-1-3
@@ -15,6 +16,7 @@ Upgrade guides
 
 .. panel-box::
 
+  * :doc:`Migrating from 1.5 to 1.6 <1-5-to-1-6>`
   * :doc:`Migrating from 1.4 to 1.5 <1-4-to-1-5>`
   * :doc:`Migrating from 1.3 to 1.4 <1-3-to-1-4>`
   * :doc:`Migrating from 1.2 to 1.3 <1-2-to-1-3>`

diff --git a/extensions/sphinx-multiversion/README.md b/extensions/sphinx-multiversion/README.md
@@ -50,6 +50,9 @@ See https://github.com/dgarcia360/sphinx-multiversion/pull/4
 
 See https://github.com/scylladb/scylla-enterprise/issues/3414
 
+### Enable paralell builds
+
+See https://github.com/scylladb/sphinx-scylladb-theme/pull/891
 
 ## Maintenance
 

diff --git a/extensions/sphinx-multiversion/setup.py b/extensions/sphinx-multiversion/setup.py
@@ -21,7 +21,7 @@
     author="Jan Holthuis",
     author_email="holthuis.jan@googlemail.com",
     url="https://holzhaus.github.io/sphinx-multiversion/",
-    version="0.2.20",
+    version="0.3.1",
     install_requires=["sphinx >= 2.1"],
     license="BSD",
     packages=["sphinx_multiversion"],

diff --git a/extensions/sphinx-multiversion/sphinx_multiversion/__init__.py b/extensions/sphinx-multiversion/sphinx_multiversion/__init__.py
@@ -2,7 +2,7 @@
 from .main import main
 from .sphinx import setup
 
-__version__ = "0.2.20"
+__version__ = "0.3.1"
 
 __all__ = [
     "setup",