fix: enhance documentation and build configuration: update versioning, fixes, and ReadTheDocs setup (#81)

laurent-laporte-pro · web-flow · commit 2fd777dae725 · 2025-01-24T19:55:30.000+01:00
diff --git a/.bumpversion.cfg b/.bumpversion.cfg
@@ -19,3 +19,7 @@ replace = release = "{new_version}"
 [bumpversion:file:python-deprecated.spec]
 search = Version:        {current_version}
 replace = Version:        {new_version}
+
+[bumpversion:file:docs/source/_static/rusty-tools-background.svg]
+search = id="deprecated-version">v{current_version}</tspan>
+replace = id="deprecated-version">v{new_version}</tspan>
diff --git a/.gitignore b/.gitignore
@@ -161,3 +161,33 @@ cython_debug/
 #  and can be added to the global gitignore or merged into this file.  For a more nuclear
 #  option (not recommended) you can uncomment the following to ignore the entire idea folder.
 .idea/
+
+### macOS template
+# General
+.DS_Store
+.AppleDouble
+.LSOverride
+
+# Icon must end with two \r
+Icon?
+![iI]con[_a-zA-Z0-9]
+
+# Thumbnails
+._*
+
+# Files that might appear in the root of a volume
+.DocumentRevisions-V100
+.fseventsd
+.Spotlight-V100
+.TemporaryItems
+.Trashes
+.VolumeIcon.icns
+.com.apple.timemachine.donotpresent
+
+# Directories potentially created on remote AFP share
+.AppleDB
+.AppleDesktop
+Network Trash Folder
+Temporary Items
+.apdisk
+
diff --git a/.readthedocs.yaml b/.readthedocs.yaml
@@ -0,0 +1,31 @@
+# Read the Docs configuration file for Sphinx projects
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the OS, Python version and other tools you might need
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.12"
+
+# Build documentation in the "docs/" directory with Sphinx
+sphinx:
+  configuration: docs/source/conf.py
+  # You can configure Sphinx to use a different builder, for instance use the dirhtml builder for simpler URLs
+  # builder: "dirhtml"
+  # Fail on all warnings to avoid broken references
+  # fail_on_warning: true
+
+# Optionally build your docs in additional formats such as PDF and ePub
+# formats:
+#   - pdf
+#   - epub
+
+# Optional but recommended, declare the Python requirements required
+# to build your documentation
+# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
+python:
+  install:
+    - requirements: docs/requirements.txt
diff --git a/CHANGELOG.rst b/CHANGELOG.rst
@@ -18,7 +18,7 @@ and this project adheres to `Semantic Versioning <https://semver.org/spec/v2.0.0
       (only in comment or documentation).
 
 
-v1.2.16 (2025-01-24)
+v1.2.17 (2024-01-25)
 ====================
 
 Bug fix release
diff --git a/docs/requirements.txt b/docs/requirements.txt
@@ -0,0 +1,22 @@
+# Project dependencies (editable mode)
+-e .
+
+# Sphinx to build the documentation
+Sphinx ~= 8.1.3
+
+# Pinned versions of dependencies to ensure compatibility with Sphinx
+alabaster >=0.7.14, <1.1.0
+babel >=2.13, <2.17.0
+docutils >=0.20, <0.22
+imagesize >=1.3, <1.5.0
+Jinja2 >=3.1, <3.2.0
+packaging >=23.0, <24.3
+Pygments >=2.17, <2.20.0
+requests >=2.30.0, <2.33.0
+snowballstemmer >=2.2, <2.3.0
+sphinxcontrib-applehelp >=1.0.7, <2.1.0
+sphinxcontrib-devhelp >=1.0.6, <2.1.0
+sphinxcontrib-htmlhelp >=2.0.6, <2.2.0
+sphinxcontrib-jsmath >=1.0.1, <1.1.0
+sphinxcontrib-qthelp >=1.0.6, <2.1.0
+sphinxcontrib-serializinghtml >=1.1.9, <2.1.0
diff --git a/docs/source/_static/banner.png b/docs/source/_static/banner.png
diff --git a/docs/source/_static/deprecated-label.png b/docs/source/_static/deprecated-label.png
diff --git a/docs/source/_static/rusty-tools-background.jpeg b/docs/source/_static/rusty-tools-background.jpeg
diff --git a/docs/source/_static/rusty-tools-background.svg b/docs/source/_static/rusty-tools-background.svg
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -70,7 +70,7 @@
 #
 # This is also used if you do content translation via gettext catalogs.
 # Usually you set "language" from the command line for these cases.
-language = None
+language = 'en'
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -1,7 +1,7 @@
 Welcome to Deprecated
 =====================
 
-.. image:: _static/banner.png
+.. image:: _static/rusty-tools-background.svg
    :alt: Deprecated: When once-stable features are removed in upcoming releases
 
 Welcome to Deprecated’s Documentation.
diff --git a/docs/source/installation.rst b/docs/source/installation.rst
@@ -6,8 +6,8 @@ Installation
 Python Version
 --------------
 
-We recommend using the latest version of Python 3. Deprecated Library supports Python 3.4
-and newer, Python 2.7 and newer, and PyPy 2.7 and 3.6.
+Our project supports Python 2.7 (for historical reasons), Python 3.4 and newer versions, as well as PyPy 2.7 and
+PyPy 3.6 and newer. We recommend using the latest version of Python 3 whenever possible.
 
 Dependencies
 ------------
diff --git a/setup.py b/setup.py
@@ -190,9 +190,6 @@ def function_three():
             "PyTest",
             "PyTest-Cov",
             "bump2version < 1",
-            "sphinx < 2",
-            # jinja2 3.0.3 was the last version to have contextfunction that sphinx 1.x needs
-            "jinja2~=3.0.3",
             "setuptools; python_version>='3.12'",
         ]
     },
diff --git a/tox.ini b/tox.ini
@@ -30,10 +30,8 @@ deps =
 
 [testenv:docs]
 basepython = python
-# jinja2 3.0.3 was the last version to have contextfunction that sphinx 1.x needs
 deps =
-    sphinx < 2
-    jinja2 == 3.0.3
+    -r docs/requirements.txt
 commands =
     sphinx-build -b html -d {envtmpdir}/doctrees docs/source/ {envtmpdir}/html
     sphinx-build -b epub -d {envtmpdir}/doctrees docs/source/ {envtmpdir}/epub

Original file line number	Diff line number	Diff line change
`@@ -70,7 +70,7 @@`
`70`	`70`	`#`
`71`	`71`	`# This is also used if you do content translation via gettext catalogs.`
`72`	`72`	`# Usually you set "language" from the command line for these cases.`
`73`		`-language = None`
	`73`	`+language = 'en'`
`74`	`74`
`75`	`75`	`# List of patterns, relative to source directory, that match files and`
`76`	`76`	`# directories to ignore when looking for source files.`