Merge branch 'main' into support-themes

Author: shenxianpeng

.github/dependabot.yml

@@ -9,7 +9,15 @@ updates:
     directory: /
     schedule:
       interval: "monthly"
+    groups:
+      github-action:
+        patterns:
+          - "*"
   - package-ecosystem: pip
     directory: /
     schedule:
       interval: "monthly"
+    groups:
+      pip:
+        patterns:
+          - "*"

.github/workflows/docs-preview.yml

@@ -0,0 +1,23 @@
+name: Read the Docs PR preview
+
+on:
+  pull_request_target:
+    types:
+      - opened
+
+permissions:
+  contents: read
+  pull-requests: write
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}
+  cancel-in-progress: true
+
+jobs:
+  documentation-links:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: readthedocs/actions/preview@v1
+        with:
+          project-slug: "gitstats"
+          single-version: "true"

.github/workflows/publish-image.yml

@@ -28,23 +28,23 @@ jobs:
         uses: actions/checkout@v4
       # Uses the `docker/login-action` action to log in to the Container registry registry using the account and password that will publish the packages. Once published, the packages are scoped to the account defined here.
       - name: Log in to the Container registry
-        uses: docker/login-action@v3.3.0
+        uses: docker/login-action@v3.4.0
         with:
           registry: ${{ env.REGISTRY }}
           username: ${{ github.actor }}
           password: ${{ secrets.GITHUB_TOKEN }}
       # This step uses [docker/metadata-action](https://github.com/docker/metadata-action#about) to extract tags and labels that will be applied to the specified image. The `id` "meta" allows the output of this step to be referenced in a subsequent step. The `images` value provides the base name for the tags and labels.
       - name: Extract metadata (tags, labels) for Docker
         id: meta
-        uses: docker/metadata-action@v5.6.1
+        uses: docker/metadata-action@v5.7.0
         with:
           images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
       # This step uses the `docker/build-push-action` action to build the image, based on your repository's `Dockerfile`. If the build succeeds, it pushes the image to GitHub Packages.
       # It uses the `context` parameter to define the build's context as the set of files located in the specified path. For more information, see "[Usage](https://github.com/docker/build-push-action#usage)" in the README of the `docker/build-push-action` repository.
       # It uses the `tags` and `labels` parameters to tag and label the image with the output from the "meta" step.
       - name: Build and push Docker image
         id: push
-        uses: docker/build-push-action@v6.9.0
+        uses: docker/build-push-action@v6.18.0
         with:
           context: .
           push: true
@@ -53,7 +53,7 @@ jobs:
 
       # This step generates an artifact attestation for the image, which is an unforgeable statement about where and how it was built. It increases supply chain security for people who consume the image. For more information, see "[AUTOTITLE](/actions/security-guides/using-artifact-attestations-to-establish-provenance-for-builds)."
       - name: Generate artifact attestation
-        uses: actions/attest-build-provenance@v2.1.0
+        uses: actions/attest-build-provenance@v2.4.0
         with:
           subject-name: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME}}
           subject-digest: ${{ steps.push.outputs.digest }}

.github/workflows/remove-preview.yml

@@ -0,0 +1,29 @@
+name: Remove PR Preview
+
+on:
+  pull_request:
+    types: [closed]
+
+jobs:
+  cleanup-preview:
+    if: github.event.pull_request.merged == true
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout gh-pages branch
+        uses: actions/checkout@v4
+        with:
+          ref: gh-pages
+          persist-credentials: true
+
+      - name: Remove preview folder
+        run: |
+          rm -rf previews/${{ github.event.pull_request.number }} || true
+
+      - name: Commit and push changes
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git add -A
+          git commit -m "Remove preview for PR #${{ github.event.pull_request.number }}"
+          git push

.github/workflows/test.yml

@@ -5,14 +5,28 @@ on:
     paths:
       - '**/*.py'
       - 'pyproject.toml'
-      - 'gitstats.conf'
+      - 'gitstats/*'
       - '.github/workflows/test.yml'
   push:
     branches:
       - "main"
   workflow_dispatch:
 
 jobs:
+  test-docs:
+    runs-on: ubuntu-latest
+    steps:
+    - name: Checkout Code
+      uses: actions/checkout@v4
+    - name: Set up Python 3.12
+      uses: actions/setup-python@v5
+      with:
+        python-version: 3.12
+    - name: Build Docs
+      run: |
+        pip install nox
+        nox -s docs
+
   test-windows:
     runs-on: windows-latest
     strategy:
@@ -26,7 +40,7 @@ jobs:
         fetch-depth: 0 # get all history.
 
     - name: Set up Python ${{ matrix.python-version }}
-      uses: actions/setup-python@v4
+      uses: actions/setup-python@v5
       with:
         python-version: ${{ matrix.python-version }}
 
@@ -42,14 +56,14 @@ jobs:
         .\venv\Scripts\activate.bat
         # for testing
         pip install .
-        gitstats . gitstats-report-windows
+        gitstats . test-report-windows -f json
 
     - name: Save GitStats Report
       if: ${{ matrix.python-version == '3.9' }}
       uses: actions/upload-artifact@v4
       with:
-        name: gitstats-report-windows
-        path: gitstats-report-windows
+        name: test-report-windows
+        path: test-report-windows
 
   test-macos:
     runs-on: macos-latest
@@ -64,7 +78,7 @@ jobs:
         fetch-depth: 0 # get all history.
 
     - name: Set up Python ${{ matrix.python-version }}
-      uses: actions/setup-python@v4
+      uses: actions/setup-python@v5
       with:
         python-version: ${{ matrix.python-version }}
 
@@ -78,20 +92,20 @@ jobs:
         source venv/bin/activate
         # for testing
         pip install .
-        gitstats . gitstats-report-macos
+        gitstats . test-report-macos -f json
 
     - name: Save GitStats Report
       if: ${{ matrix.python-version == '3.9' }}
       uses: actions/upload-artifact@v4
       with:
-        name: gitstats-report-macos
-        path: gitstats-report-macos
+        name: test-report-macos
+        path: test-report-macos
 
   test-linux:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
+        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13", "3.14.0-beta.1"]
 
     steps:
     - name: Checkout Code
@@ -100,36 +114,33 @@ jobs:
         fetch-depth: 0 # get all history.
 
     - name: Set up Python ${{ matrix.python-version }}
-      uses: actions/setup-python@v4
+      uses: actions/setup-python@v5
       with:
         python-version: ${{ matrix.python-version }}
 
     - name: Install Dependencies
       run: |
-        sudo apt-get update
-        sudo apt-get install -y gnuplot
+        pip install nox
+        nox -s install-deps
 
     - name: Generate GitStats Report
       run: |
-        python3 -m venv venv
-        source venv/bin/activate
-        # for testing
-        pip install .
-        gitstats . gitstats-report
+        pip install nox
+        nox -s build
 
     - name: Save GitStats Report
       if: ${{ matrix.python-version == '3.9' }}
       uses: actions/upload-artifact@v4
       with:
-        name: gitstats-report
-        path: gitstats-report
+        name: test-report
+        path: test-report
 
     - name: Deploy to GitHub Pages for PR
       if: ${{ github.event_name == 'pull_request' && matrix.python-version == '3.9' }}
       uses: peaceiris/actions-gh-pages@v4
       with:
         github_token: ${{ secrets.GITHUB_TOKEN }}
-        publish_dir: gitstats-report
+        publish_dir: test-report
         # Configure a unique preview link for each pull request
         destination_dir: previews/${{ github.event.pull_request.number }}
 
@@ -138,7 +149,7 @@ jobs:
       uses: peaceiris/actions-gh-pages@v4
       with:
         github_token: ${{ secrets.GITHUB_TOKEN }}
-        publish_dir: gitstats-report
+        publish_dir: test-report
         keep_files: true # do not remove example reports
 
     - name: Add PR Comment with Preview Link

.gitignore

@@ -1,8 +1,11 @@
 venv/
 .venv/
+__pycache__
 gitstats/__pycache__/
 gitstats.egg-info
 gitstory.egg-info
 build/
 gitstats-report
 test-report
+test-report.json
+docs/build

.gitpod.yml

@@ -6,5 +6,8 @@
 
 tasks:
   - name: Install & Build
-    init: sudo apt-get install -y --no-install-recommends gnuplot
-    command: make preview
+    init: |
+      pip install nox
+      nox -s install-deps
+      nox -s build
+    command: nox -s preview

.mailmap

@@ -0,0 +1,2 @@
+Xianpeng Shen   <[email protected]>
+Pinhong Ma      <[email protected]>

.pre-commit-config.yaml

@@ -1,3 +1,6 @@
+ci:
+  autoupdate_schedule: quarterly
+
 repos:
 -   repo: https://github.com/pre-commit/pre-commit-hooks
     rev: v5.0.0
@@ -7,10 +10,19 @@ repos:
     -   id: end-of-file-fixer
     -   id: trailing-whitespace
     -   id: requirements-txt-fixer
+
+-   repo: https://github.com/pre-commit/pygrep-hooks
+    rev: "v1.10.0"
+    hooks:
+    - id: rst-backticks
+    - id: rst-directive-colons
+    - id: rst-inline-touching-normal
+
 -   repo: https://github.com/pre-commit/mirrors-mypy
     rev: v1.13.0
     hooks:
     -   id: mypy
+        additional_dependencies: [types-requests]
 -   repo: https://github.com/astral-sh/ruff-pre-commit
     # Ruff version.
     rev: v0.8.6

.readthedocs.yaml

@@ -0,0 +1,23 @@
+# Read the Docs configuration file
+# 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-24.04
+  tools:
+    python: "3.12" # use 3.12 because 3.13 removed imghdr module, it will cause error
+
+# Build documentation in the "docs/" directory with Sphinx
+sphinx:
+   configuration: docs/source/conf.py
+   fail_on_warning: true
+
+# Optionally, 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