Merge pull request #118 from sphinx-contrib/deploy-pages

Fix GitHub Pages deployment, update remaining references to old repo and TravisCI, add more pre-commit hooks

.github/workflows/build.yml

@@ -38,9 +38,10 @@ jobs:
         mkdir html
         git fetch --all
         python -I -m sphinx_multiversion -W docs html
+        cp assets/gh-pages-redirect.html html/index.html
 
     - name: Upload the Docs
-      uses: actions/upload-artifact@v4
+      uses: actions/upload-pages-artifact@v3
       if: matrix.os == 'ubuntu-latest' && matrix.version == '3.12'
       with:
         name: docs
@@ -61,7 +62,7 @@ jobs:
 
   deploy-docs:
     name: Deploy Docs to GitHub Pages
-    if: ${{ startsWith(github.ref, 'refs/tags/') || github.ref == 'refs/heads/master' }}
+    if: ${{ startsWith(github.ref, 'refs/tags/') || github.ref == 'refs/heads/main' }}
     runs-on: ubuntu-latest
     needs: [build]
     permissions:
@@ -119,4 +120,3 @@ jobs:
 
     - name: Publish Distributions to PyPI
       uses: pypa/gh-action-pypi-publish@release/v1
-

.pre-commit-config.yaml

@@ -2,17 +2,67 @@ repos:
 - repo: https://github.com/pre-commit/pre-commit-hooks
   rev: v4.6.0
   hooks:
-  - id: trailing-whitespace
-  - id: check-merge-conflict
-  - id: check-yaml
-  - id: check-executables-have-shebangs
-  - id: mixed-line-ending
+    - id: check-added-large-files
+      args: ["--maxkb=500"]
+    - id: check-ast
+    - id: fix-byte-order-marker
+    - id: check-builtin-literals
+    - id: check-case-conflict
+    - id: check-docstring-first
+    - id: check-executables-have-shebangs
+    - id: check-json
+    - id: check-shebang-scripts-are-executable
+    - id: pretty-format-json
+      args: ["--autofix"]
+    - id: check-merge-conflict
+    - id: check-symlinks
+    - id: check-toml
+    - id: check-vcs-permalinks
+    - id: check-xml
+    - id: check-yaml
+    - id: debug-statements
+    - id: destroyed-symlinks
+    - id: detect-private-key
+    - id: end-of-file-fixer
+    - id: file-contents-sorter
+    - id: fix-byte-order-marker
+    - id: forbid-new-submodules
+    - id: mixed-line-ending
+      args: ["--fix=lf"]
+    - id: requirements-txt-fixer
+    - id: sort-simple-yaml
+    - id: trailing-whitespace
 - repo: https://github.com/astral-sh/ruff-pre-commit
-  rev: v0.6.8
+  rev: v0.6.9
   hooks:
     - id: ruff
       args: [ --fix ]
     - id: ruff-format
+- repo: https://github.com/codespell-project/codespell
+  rev: v2.3.0
+  hooks:
+  - id: codespell
+    args: [
+      --ignore-words=.codespellignore
+    ]
+- repo: https://github.com/markdownlint/markdownlint
+  rev: v0.12.0
+  hooks:
+  - id: markdownlint
+- repo: https://github.com/Holzhaus/sourceheaders
+  rev: v0.0.4
+  hooks:
+  - id: sourceheaders
+- repo: https://github.com/PyCQA/bandit
+  rev: "1.7.10"
+  hooks:
+  - id: bandit
+    args: ["-c", "pyproject.toml", "--"]
+    additional_dependencies: ["bandit[toml]"]
+- repo: https://github.com/gitleaks/gitleaks
+  rev: v8.20.0
+  hooks:
+    - id: gitleaks
 - repo: local
   hooks:
   - id: version-check

.pre-commit/version_check.py

@@ -1,4 +1,31 @@
 #!/usr/bin/env python
+# -*- coding: utf-8 -*-
+# Copyright (c) 2024 Jan Holthuis <jan.holthuis@rub.de>
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are met:
+#
+# 1. Redistributions of source code must retain the above copyright notice,
+# this list of conditions and the following disclaimer.
+#
+# 2. Redistributions in binary form must reproduce the above copyright notice,
+# this list of conditions and the following disclaimer in the documentation
+# and/or other materials provided with the distribution.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+# ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+# POSSIBILITY OF SUCH DAMAGE.
+#
+# SPDX-License-Identifier: BSD-2-Clause
+
 import importlib.util
 import os
 import pkgutil

.sourceheaders.toml

@@ -0,0 +1,5 @@
+[general]
+license = "BSD-2-Clause"
+copyright_holder = "Jan Holthuis <jan.holthuis@rub.de>"
+prefer_inline = true
+width = 79

README.md

@@ -1,8 +1,15 @@
-# sphinx-multiversion [![Build Status](https://travis-ci.org/Holzhaus/sphinx-multiversion.svg?branch=master)](https://travis-ci.org/Holzhaus/sphinx-multiversion)
+# sphinx-multiversion [![License][license-badge]][license][![Build][build-badge]][build][![pre-commit.ci][pre-commit-badge]][pre-commit]
 
 Sphinx extension for building self-hosted versioned docs.
 
 This extension aims to provide a clean implementation that tries to avoid
 messing with Sphinx internals as much as possible.
 
-Documentation can be found at: https://holzhaus.github.io/sphinx-multiversion/
+Documentation can be found at: <https://sphinx-contrib.github.io/multiversion/>
+
+[license]: https://github.com/sphinx-contrib/multiversion/blob/main/LICENSE
+[license-badge]: https://img.shields.io/github/license/sphinx-contrib/multiversion
+[build]: https://github.com/sphinx-contrib/multiversion/actions?query=branch%3Amain
+[build-badge]: https://img.shields.io/github/actions/workflow/status/sphinx-contrib/multiversion/build.yml?branch=main
+[pre-commit]: https://results.pre-commit.ci/latest/github/sphinx-contrib/multiversion/main
+[pre-commit-badge]: https://results.pre-commit.ci/badge/github/sphinx-contrib/multiversion/main.svg

assets/gh-pages-redirect.html

@@ -1,9 +1,9 @@
 <!DOCTYPE html>
 <html>
   <head>
-    <title>Redirecting to https://holzhaus.github.io/sphinx-multiversion/master/</title>
+    <title>Redirecting to https://sphinx-contrib.github.io/multiversion/main/</title>
     <meta charset="utf-8">
-    <meta http-equiv="refresh" content="0; URL=https://holzhaus.github.io/sphinx-multiversion/master/index.html">
-    <link rel="canonical" href="https://holzhaus.github.io/sphinx-multiversion/master/index.html">
+    <meta http-equiv="refresh" content="0; URL=https://sphinx-contrib.github.io/multiversion/main/index.html">
+    <link rel="canonical" href="https://sphinx-contrib.github.io/multiversion/main/index.html">
   </head>
 </html>

docs/changelog.rst

@@ -60,22 +60,22 @@ Version 0.1.0 (2020-03-11)
 * Initial release
 
 
-.. _issue4: https://github.com/Holzhaus/sphinx-multiversion/issues/4
-.. _issue7: https://github.com/Holzhaus/sphinx-multiversion/issues/7
-.. _issue9: https://github.com/Holzhaus/sphinx-multiversion/issues/9
-.. _issue11: https://github.com/Holzhaus/sphinx-multiversion/issues/11
-.. _issue12: https://github.com/Holzhaus/sphinx-multiversion/issues/12
-.. _issue13: https://github.com/Holzhaus/sphinx-multiversion/issues/13
-.. _issue18: https://github.com/Holzhaus/sphinx-multiversion/issues/18
-.. _issue19: https://github.com/Holzhaus/sphinx-multiversion/issues/19
-.. _issue22: https://github.com/Holzhaus/sphinx-multiversion/issues/22
-.. _issue23: https://github.com/Holzhaus/sphinx-multiversion/issues/23
-.. _issue24: https://github.com/Holzhaus/sphinx-multiversion/issues/24
-.. _issue25: https://github.com/Holzhaus/sphinx-multiversion/issues/25
-.. _issue26: https://github.com/Holzhaus/sphinx-multiversion/issues/26
-.. _issue28: https://github.com/Holzhaus/sphinx-multiversion/issues/28
-.. _issue30: https://github.com/Holzhaus/sphinx-multiversion/issues/30
-.. _issue31: https://github.com/Holzhaus/sphinx-multiversion/issues/31
-.. _issue35: https://github.com/Holzhaus/sphinx-multiversion/issues/35
-.. _issue36: https://github.com/Holzhaus/sphinx-multiversion/issues/36
+.. _issue4: https://github.com/sphinx-contrib/multiversion/issues/4
+.. _issue7: https://github.com/sphinx-contrib/multiversion/issues/7
+.. _issue9: https://github.com/sphinx-contrib/multiversion/issues/9
+.. _issue11: https://github.com/sphinx-contrib/multiversion/issues/11
+.. _issue12: https://github.com/sphinx-contrib/multiversion/issues/12
+.. _issue13: https://github.com/sphinx-contrib/multiversion/issues/13
+.. _issue18: https://github.com/sphinx-contrib/multiversion/issues/18
+.. _issue19: https://github.com/sphinx-contrib/multiversion/issues/19
+.. _issue22: https://github.com/sphinx-contrib/multiversion/issues/22
+.. _issue23: https://github.com/sphinx-contrib/multiversion/issues/23
+.. _issue24: https://github.com/sphinx-contrib/multiversion/issues/24
+.. _issue25: https://github.com/sphinx-contrib/multiversion/issues/25
+.. _issue26: https://github.com/sphinx-contrib/multiversion/issues/26
+.. _issue28: https://github.com/sphinx-contrib/multiversion/issues/28
+.. _issue30: https://github.com/sphinx-contrib/multiversion/issues/30
+.. _issue31: https://github.com/sphinx-contrib/multiversion/issues/31
+.. _issue35: https://github.com/sphinx-contrib/multiversion/issues/35
+.. _issue36: https://github.com/sphinx-contrib/multiversion/issues/36
 .. _pythonflags: https://docs.python.org/3/using/cmdline.html#miscellaneous-options

docs/conf.py

@@ -1,4 +1,30 @@
 # -*- coding: utf-8 -*-
+# Copyright (c) 2024 Jan Holthuis <jan.holthuis@rub.de>
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are met:
+#
+# 1. Redistributions of source code must retain the above copyright notice,
+# this list of conditions and the following disclaimer.
+#
+# 2. Redistributions in binary form must reproduce the above copyright notice,
+# this list of conditions and the following disclaimer in the documentation
+# and/or other materials provided with the distribution.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+# ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+# POSSIBILITY OF SUCH DAMAGE.
+#
+# SPDX-License-Identifier: BSD-2-Clause
+
 """Sphinx configuration file."""
 
 import time
@@ -11,11 +37,10 @@
 
 html_theme = "alabaster"
 html_theme_options = {
-    "github_repo": "sphinx-multiversion",
-    "github_user": "Holzhaus",
+    "github_repo": "multiversion",
+    "github_user": "sphinx-contrib",
     "github_banner": True,
     "github_button": True,
-    "travis_button": True,
     "show_relbar_bottom": True,
 }
 html_last_updated_fmt = "%c"
@@ -41,4 +66,4 @@
 }
 
 smv_remote_whitelist = r"^origin$"
-smv_branch_whitelist = r"^master$"
+smv_branch_whitelist = r"^main$"

docs/configuration.rst

@@ -85,7 +85,7 @@ Here are some examples:
 Output Directory Format
 =======================
 
-Each version will be built into a seperate subdirectory of the Sphinx output directory.
+Each version will be built into a separate subdirectory of the Sphinx output directory.
 The ``smv_outputdir_format`` setting determines the directory structure for the subdirectories. It is a new-style Python formatting string with two parameters - ``ref`` and ``config``.
 
 Here are some examples:
@@ -113,7 +113,7 @@ You can override configuration variables the same way as you're used to with ``s
 
 Since ``sphinx-multiversion`` copies the branch data into a temporary directory and builds them there while leaving the current working directory unchanged, relative paths in your :file:`conf.py` will refer to the path of the version *you're building from*, not the path of the version you are trying to build documentation for.
 
-Sometimes it might be necessary to override the configured path via a command line overide.
+Sometimes it might be necessary to override the configured path via a command line argument.
 ``sphinx-multiversion`` allows you to insert placeholders into your override strings that will automatically be replaced with the correct value for the version you're building the documentation for.
 
 Here's an example for the `exhale extension <exhale_>`_:

docs/index.rst

@@ -1,13 +1,13 @@
 =============================
-sphinx-multiversion |version|
+sphinx-multiversion |release|
 =============================
 
 A Sphinx extension for building self-hosted versioned documentation.
 
 Project Links
 =============
 
-* Source code: https://github.com/Holzhaus/sphinx-multiversion
+* Source code: https://github.com/sphinx-contrib/multiversion
 
 .. toctree::
     :maxdepth: 3

docs/install.rst

@@ -4,7 +4,7 @@
 Installation
 ============
 
-You can install ``sphinx-multiversion`` via `pip <pip_>`_ or directly from :file:`setup.py`.
+You can install ``sphinx-multiversion`` via `pip <pip_>`_.
 
 Install from PyPi
 ===================
@@ -23,18 +23,19 @@ repository:
 
 .. code-block:: bash
 
-    pip install git+https://github.com/Holzhaus/sphinx-multiversion.git
+    pip install git+https://github.com/sphinx-contrib/multiversion.git
 
-Install via :file:`setup.py`
-============================
+Install from local clone
+========================
 
-It's also possible to clone the Git repository and install the extension using its :file:`setup.py`:
+It's also possible to clone the Git repository and install the extension from
+the local clone.
 
 .. code-block:: bash
 
-    git clone https://github.com/Holzhaus/sphinx-multiversion.git
-    cd sphinx-multiversion
-    python setup.py install
+    git clone https://github.com/sphinx-contrib/multiversion.git
+    cd multiversion
+    pip install .
 
 
 .. _pip: https://pip.pypa.io/en/stable/

pyproject.toml

@@ -38,5 +38,17 @@ include = [
     "/sphinx_multiversion",
 ]
 
+[tool.bandit]
+skips = [
+    # Asserts are actually fine for checking the developer's assumptions, we
+    # "just" mustn't rely these assert in production code.
+    "B101",
+    # We need `subprocess` module.
+    "B404",
+    # As long as we don't use `shell=True` when spawning a subprocess, this
+    # should be fine.
+    "B603",
+]
+
 [tool.ruff]
 line-length = 79

sphinx_multiversion/__init__.py

@@ -1,4 +1,30 @@
 # -*- coding: utf-8 -*-
+# Copyright (c) 2024 Jan Holthuis <jan.holthuis@rub.de>
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are met:
+#
+# 1. Redistributions of source code must retain the above copyright notice,
+# this list of conditions and the following disclaimer.
+#
+# 2. Redistributions in binary form must reproduce the above copyright notice,
+# this list of conditions and the following disclaimer in the documentation
+# and/or other materials provided with the distribution.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+# ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+# POSSIBILITY OF SUCH DAMAGE.
+#
+# SPDX-License-Identifier: BSD-2-Clause
+
 from .sphinx import setup
 from .main import main