Docs updates, run precommit.ci, and use Ruff (#37)

- Update a handful of lines in the docs for clarity or grammar purposes
- Run the new `precommit.ci` workflow to auto-clean the source code
- Switch linting over to `ruff` (via `hatch fmt`) and resolve all lint errors

.pre-commit-config.yaml

@@ -14,48 +14,27 @@ repos:
       rev: 1.8.0
       hooks:
           - id: pyproject-fmt
-    - repo: https://github.com/rstcheck/rstcheck
-      rev: v6.2.0
-      hooks:
-          - id: rstcheck
-            additional_dependencies:
-                - sphinx==6.1.3
-                - tomli==2.0.1
-    - repo: https://github.com/sphinx-contrib/sphinx-lint
-      rev: v0.9.1
-      hooks:
-          - id: sphinx-lint
     - repo: https://github.com/asottile/pyupgrade
       rev: v3.15.2
       hooks:
           - id: pyupgrade
             args: [--py39-plus]
+    - repo: https://github.com/hadialqattan/pycln
+      rev: "v2.4.0"
+      hooks:
+          - id: pycln
+            args: [--all]
     - repo: https://github.com/adamchainz/django-upgrade
       rev: 1.16.0
       hooks:
           - id: django-upgrade
             args: [--target-version, "3.2"]
-    - repo: https://github.com/psf/black-pre-commit-mirror
-      rev: 24.4.2
-      hooks:
-          - id: black
-    - repo: https://github.com/adamchainz/blacken-docs
-      rev: 1.16.0
-      hooks:
-          - id: blacken-docs
-            additional_dependencies:
-                - black==23.1.0
-    - repo: https://github.com/pycqa/isort
-      rev: 5.13.2
-      hooks:
-          - id: isort
-            name: isort (python)
-    - repo: https://github.com/PyCQA/flake8
-      rev: 7.0.0
-      hooks:
-          - id: flake8
-            additional_dependencies:
-                - flake8-bugbear
-                - flake8-comprehensions
-                - flake8-logging
-                - flake8-tidy-imports
+    - repo: https://github.com/astral-sh/ruff-pre-commit
+      # Ruff version.
+      rev: v0.6.6
+      hooks:
+          # Run the linter.
+          - id: ruff
+            args: [--fix]
+          # Run the formatter.
+          - id: ruff-format

CHANGELOG.md

@@ -40,13 +40,13 @@ Using the following categories, list your changes in this order:
 
 ### Fixed
 
--   Fix crash when running `manage.py collectstatic` if Django's `settings.py:STATIC_ROOT` is a `Path` object.
+-   Fix crash when running `manage.py collectstatic` when Django's `settings.py:STATIC_ROOT` is a `Path` object.
 
 ## [2.0.0](https://github.com/Archmonger/ServeStatic/compare/1.2.0...2.0.0) - 2024-09-12
 
 ### Added
 
--   Django `settings.py:SERVESTATIC_USE_MANIFEST` utilize the Django manifest rather than scanning the filesystem.
+-   Django `settings.py:SERVESTATIC_USE_MANIFEST` will allow ServeStatic to use the Django manifest rather than scanning the filesystem.
     -   When also using ServeStatic's `CompressedManifestStaticFilesStorage` backend, ServeStatic will no longer need to call `os.stat`.
 
 ### Changed

docs/mkdocs.yml

@@ -98,9 +98,9 @@ watch:
     - ../LICENSE.md
 
 site_name: ServeStatic
-site_author: Archmonger
+site_author: Mark Bakhit (Archmonger)
 site_description: Production-grade static file server for Python web apps.
-copyright: '&copy;<div id="year"></div> <script>document.getElementById("year").innerHTML = new Date().getFullYear();</script> Archmonger'
+copyright: '&copy;<div id="year"></div> <script>document.getElementById("year").innerHTML = new Date().getFullYear();</script> Mark Bakhit (Archmonger)'
 repo_url: https://github.com/Archmonger/ServeStatic
 site_url: https://archmonger.github.io/ServeStatic/
 repo_name: ServeStatic (GitHub)

docs/src/contributing.md

@@ -1,112 +1,59 @@
-# Contributing
+## Creating a development environment
 
-## Tool Setup
+If you plan to make code changes to this repository, you will need to install the following dependencies first:
 
-### `python`
+-   [Git](https://git-scm.com/downloads)
+-   [Python 3.9+](https://www.python.org/downloads/)
+-   [Hatch](https://hatch.pypa.io/latest/)
 
-To contribute code or documentation updates, an installation of Python 3 is required.
+Once you finish installing these dependencies, you can clone this repository:
 
-### `hatch`
-
-This project utilizes [`hatch`](https://hatch.pypa.io/latest/) to manage Python environments for development and testing.  Follow
-[the `hatch` installation instructions](https://hatch.pypa.io/latest/install/) before continuing through this document.
-
-### `pre-commit`
-
-Additionally, this project uses [`pre-commit`](https://pre-commit.com/) Git hooks to run linting and formatting checks against each commit.  See [the `pre-commit` installation instructions](https://pre-commit.com/#install) for how to install this tool.
-
-Once installed, run `pre-commit install` to set up the git hook scripts:
-
-``` shell
-$ pre-commit install
-pre-commit installed at .git/hooks/pre-commit
-```
-
-### Git
-
-Clone the repository using:
-
-``` shell
+```shell
 git clone https://github.com/Archmonger/ServeStatic.git
 cd ServeStatic
 ```
 
-All example commands are expected to be run from the `ServeStatic` folder.
-
-## Code Contributions
-
-Ensure you have followed the [tool setup](#tool-setup) instructions before following the instructions below.
-
-### Development
-
-#### Linting
-
-The project uses `flake8` and `isort` for linting and uses `black` to format code.  To run the all linters:
-
-``` shell
-hatch run lint:check
-```
-
-Or select a specific linter:
+## Executing test environment commands
 
-``` shell
-hatch run lint:flake8
-```
-
-!!! tip
-
-    Linting is likely to see an update in the near future to use `ruff` for linting and formatting.
-
-### Testing
-
-Tests are run across a matrix of Python and Django versions to ensure full compatibility with all supported versions.
+By utilizing `hatch`, the following commands are available to manage the development environment.
 
-#### Full Test Suite
+### Tests
 
-To run the full test suite, using the system Python:
+| Command | Description |
+| --- | --- |
+| `hatch test` | Run Python tests using the current environment's Python version |
+| `hatch test --all` | Run tests using all compatible Python and Django versions |
+| `hatch test --python 3.9` | Run tests using a specific Python version |
+| `hatch test --include "django=5.1"` | Run tests using a specific Django version |
+| `hatch test -k test_get_js_static_file` | Run only a specific test |
 
-``` shell
-hatch test
-```
-
-To select a particular Python version:
-
-``` shell
-hatch test --python 3.9
-```
+??? question "What other arguments are available to me?"
 
-!!! tip
+    The `hatch test` command is a wrapper for `pytest`. Hatch "intercepts" a handful of arguments, which can be previewed by typing `hatch test --help`.
 
-    `hatch` can manage Python versions for you, for example installing Python 3.9: `hatch python install 3.9`
-
-    See the [hatch documentation](https://hatch.pypa.io/latest/tutorials/python/manage/)
-
-To select a particular Django version:
-
-``` shell
-hatch test --include "django=5.1"
-```
-
-#### Specific Test(s)
-
-To run only a specific test:
-
-``` shell
-hatch test -k test_get_js_static_file
-```
+    Any additional arguments in the `test` command are directly passed on to pytest. See the [pytest documentation](https://docs.pytest.org/en/8.3.x/reference/reference.html#command-line-flags) for what additional arguments are available.
 
-!!! tip
+### Linting and Formatting
 
-    Additional arguments are passed on to pytest.
+| Command | Description |
+| --- | --- |
+| `hatch fmt` | Run all linters and formatters |
+| `hatch fmt --check` | Run all linters and formatters, but do not save fixes to the disk |
+| `hatch fmt --linter` | Run only linters |
+| `hatch fmt --formatter` | Run only formatters |
+| `hatch run precommit:check` | Run all [`pre-commit`](https://pre-commit.com/) checks configured within this repository |
+| `hatch run precommit:update` | Update the [`pre-commit`](https://pre-commit.com/) hooks configured within this repository |
 
-    See the [pytest documentation](https://docs.pytest.org/en/8.3.x/reference/reference.html#command-line-flags) for options
+### Documentation
 
-## Documentation Contributions
+| Command | Description |
+| --- | --- |
+| `hatch run docs:serve` | Start the `mkdocs` server to view documentation locally |
+| `hatch run docs:build` | Build the documentation |
+| `hatch run docs:linkcheck` | Check for broken links in the documentation |
 
-Ensure you have followed the [tool setup](#tool-setup) instructions before following the instructions below.
+??? tip "Configure your IDE for linting"
 
-### Modifying Documentation
+    This repository uses `hatch fmt` for linting and formatting, which is a [modestly customized](https://hatch.pypa.io/latest/config/internal/static-analysis/#default-settings) version of [`ruff`](https://github.com/astral-sh/ruff).
 
-1. Start the `mkdocs` server by running `hatch run docs:serve`
-1. Visit [the documentation site](http://localhost:8000/) in your preferred browser
-1. Edit the documentation.  The site will load change as documentation files change.
+    You can install `ruff` as a plugin to your preferred code editor to create a similar environment.

docs/src/dictionary.txt

@@ -35,3 +35,4 @@ linter
 linters
 linting
 pytest
+formatters

docs/src/django-settings.md

@@ -30,7 +30,7 @@ Find and serve files using Django's manifest file.
 
 This is the most efficient way to determine what files are available, but it requires that you are using a [manifest-compatible](https://docs.djangoproject.com/en/stable/ref/contrib/staticfiles/#manifeststaticfilesstorage) storage backend.
 
-When using ServeStatic's [`CompressedManifestStaticFilesStorage`](./django.md#step-2-add-compression-and-caching-support) storage backend, ServeStatic will no longer need to call `os.stat` on each file during startup which improves startup speeds.
+When using ServeStatic's [`CompressedManifestStaticFilesStorage`](./django.md#step-2-add-compression-and-caching-support) storage backend, ServeStatic will no longer need to call `os.stat` on each file during startup.
 
 ---
 
@@ -138,8 +138,9 @@ def force_download_pdfs(headers, path, url):
         url: The host-relative URL of the file e.g. `/static/styles/app.css`
 
     """
-    if path.endswith('.pdf'):
-        headers['Content-Disposition'] = 'attachment'
+    if path.endswith(".pdf"):
+        headers["Content-Disposition"] = "attachment"
+
 
 SERVESTATIC_ADD_HEADERS_FUNCTION = force_download_pdfs
 ```
@@ -167,7 +168,8 @@ def immutable_file_test(path, url):
     """
     # Match filename with 12 hex digits before the extension
     # e.g. app.db8f2edc0c8a.js
-    return re.match(r'^.+\.[0-9a-f]{12}\..+$', url)
+    return re.match(r"^.+\.[0-9a-f]{12}\..+$", url)
+
 
 SERVESTATIC_IMMUTABLE_FILE_TEST = immutable_file_test
 ```

docs/src/django.md

@@ -10,10 +10,9 @@ Edit your `settings.py` file and add ServeStatic to the `MIDDLEWARE` list. The S
 
 ```python linenums="0"
 MIDDLEWARE = [
-    ...,
     "django.middleware.security.SecurityMiddleware",
     "servestatic.middleware.ServeStaticMiddleware",
-    ...,
+    # ...
 ]
 ```
 
@@ -29,7 +28,7 @@ ServeStatic comes with a storage backend which compresses your files and hashes
 
 ```python linenums="0"
 STORAGES = {
-    ...,
+    # ...
     "staticfiles": {
         "BACKEND": "servestatic.storage.CompressedManifestStaticFilesStorage",
     },
@@ -146,9 +145,9 @@ You can disable Django's static file handling and allow ServeStatic to take over
 
 ```python linenums="0"
 INSTALLED_APPS = [
-    ...,
+    # ...
     "servestatic.runserver_nostatic",
     "django.contrib.staticfiles",
-    ...,
+    # ...
 ]
 ```

docs/src/quick-start.md

@@ -16,7 +16,6 @@ Edit your `settings.py` file and add `ServeStatic` to the `MIDDLEWARE` list, abo
 
 ```python linenums="0"
 MIDDLEWARE = [
-    # ...
     "django.middleware.security.SecurityMiddleware",
     "servestatic.middleware.ServeStaticMiddleware",
     # ...

docs/src/servestatic.md

@@ -58,7 +58,7 @@ If you want to something other than `index.html` as the index file, then you can
 A dictionary mapping file extensions (lowercase) to the mimetype for that extension. For example:
 
 ```python linenums="0"
-{'.foo': 'application/x-foo'}
+{".foo": "application/x-foo"}
 ```
 
 Note that ServeStatic ships with its own default set of mimetypes and does not use the system-supplied ones (e.g. `/etc/mime.types`). This ensures that it behaves consistently regardless of the environment in which it's run. View the defaults in the `media_types.py` file.
@@ -114,13 +114,14 @@ def force_download_pdfs(headers, path, url):
         None. Changes should be made by modifying the headers \
         dictionary directly.
     """
-    if path.endswith('.pdf'):
-        headers['Content-Disposition'] = 'attachment'
+    if path.endswith(".pdf"):
+        headers["Content-Disposition"] = "attachment"
+
 
 application = ServeStatic(
     application,
     add_headers_function=force_download_pdfs,
-    )
+)
 ```
 
 ---
@@ -151,7 +152,7 @@ def immutable_file_test(path, url):
     """
     # Match filename with 12 hex digits before the extension
     # e.g. app.db8f2edc0c8a.js
-    return re.match(r'^.+\.[0-9a-f]{12}\..+$', url)
+    return re.match(r"^.+\.[0-9a-f]{12}\..+$", url)
 ```
 
 ## Compression Support