Feature/adopt md

.github/workflows/changelog.yml

@@ -1,10 +1,17 @@
 name: Check Changelog
+
 on:
   pull_request:
     # opened/synchronize/reopened: Check changelog when PR is created or updated
     # labeled/unlabeled: Re-run check when "no changelog" label is added/removed
     types: [opened, synchronize, reopened, labeled, unlabeled]
     branches: [develop, main]
+
+concurrency:
+  # Cancel existing job(s) for workflow when a new one is queued
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
 jobs:
   check-changelog:
     name: Verify Changelog Updated

.github/workflows/codeql.yml

@@ -0,0 +1,96 @@
+name: "CodeQL"
+
+on:
+  push:
+    branches: [main, develop]
+  pull_request:
+    # The branches below must be a subset of the branches above
+    branches: [main, develop]
+  schedule:
+    - cron: '34 21 * * 1'
+
+concurrency:
+  # Cancel existing job(s) for workflow when a new one is queued
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  analyze:
+    name: Analyze (${{ matrix.language }})
+    # Runner size impacts CodeQL analysis time. To learn more, please see:
+    #   - https://gh.io/recommended-hardware-resources-for-running-codeql
+    #   - https://gh.io/supported-runners-and-hardware-resources
+    #   - https://gh.io/using-larger-runners (GitHub.com only)
+    # Consider using larger runners or machines with greater resources for possible analysis time improvements.
+    runs-on: ${{ (matrix.language == 'swift' && 'macos-latest') || 'ubuntu-latest' }}
+    permissions:
+      # required for all workflows
+      security-events: write
+
+      # required to fetch internal or private CodeQL packs
+      packages: read
+
+      # only required for workflows in private repositories
+      actions: read
+      contents: read
+
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - language: actions
+            build-mode: none
+          - language: python
+            build-mode: none
+            # CodeQL supports the following values keywords for 'language': 'actions', 'c-cpp', 'csharp', 'go', 'java-kotlin', 'javascript-typescript', 'python', 'ruby', 'rust', 'swift'
+            # Use `c-cpp` to analyze code written in C, C++ or both
+            # Use 'java-kotlin' to analyze code written in Java, Kotlin or both
+            # Use 'javascript-typescript' to analyze code written in JavaScript, TypeScript or both
+            # To learn more about changing the languages that are analyzed or customizing the build mode for your analysis,
+            # see https://docs.github.com/en/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/customizing-your-advanced-setup-for-code-scanning.
+            # If you are analyzing a compiled language, you can modify the 'build-mode' for that language to customize how
+            # your codebase is analyzed, see https://docs.github.com/en/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/codeql-code-scanning-for-compiled-languages
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      # Add any setup steps before running the `github/codeql-action/init` action.
+      # This includes steps like installing compilers or runtimes (`actions/setup-node`
+      # or others). This is typically only required for manual builds.
+      # - name: Setup runtime (example)
+      #   uses: actions/setup-example@v1
+
+      # Initializes the CodeQL tools for scanning.
+      - name: Initialize CodeQL
+        uses: github/codeql-action/init@v4
+        with:
+          languages: ${{ matrix.language }}
+          build-mode: ${{ matrix.build-mode }}
+          # If you wish to specify custom queries, you can do so here or in a config file.
+          # By default, queries listed here will override any specified in a config file.
+          # Prefix the list here with "+" to use these queries and those in the config file.
+
+          # For more details on CodeQL's query packs, refer to: https://docs.github.com/en/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/configuring-code-scanning#using-queries-in-ql-packs
+          # queries: security-extended,security-and-quality
+
+      # If the analyze step fails for one of the languages you are analyzing with
+      # "We were unable to automatically build your code", modify the matrix above
+      # to set the build mode to "manual" for that language. Then modify this step
+      # to build your code.
+      # ℹ️ Command-line programs to run using the OS shell.
+      # 📚 See https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idstepsrun
+      - name: Run manual build steps
+        if: matrix.build-mode == 'manual'
+        shell: bash
+        run: |
+          echo 'If you are using a "manual" build mode for one or more of the' \
+            'languages you are analyzing, replace this with the commands to build' \
+            'your code, for example:'
+          echo '  make bootstrap'
+          echo '  make release'
+          exit 1
+
+      - name: Perform CodeQL Analysis
+        uses: github/codeql-action/analyze@v4
+        with:
+          category: "/language:${{matrix.language}}"

.github/workflows/python-publish.yml

@@ -18,6 +18,11 @@ on:
 permissions:
   contents: read
 
+concurrency:
+  # Cancel existing job(s) for workflow when a new one is queued
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
 jobs:
   pypi-publish:
     name: Upload release to PyPI
@@ -26,7 +31,7 @@ jobs:
       name: pypi
       url: https://pypi.org/project/viapy/
     permissions:
-      id-token: write # IMPORTANT: this permission is mandatory for trusted publishing
+      id-token: write  # IMPORTANT: this permission is mandatory for trusted publishing
     if: github.event_name == 'release' || (github.event_name == 'workflow_dispatch' && github.ref == 'main')
     steps:
       - uses: actions/checkout@v4

.github/workflows/ruff-checks.yml

@@ -1,10 +1,17 @@
 name: Check Ruff linter + formatter
+
 on:
   # Run on pull requests to develop or main
   pull_request:
     branches: [develop, main]
   # Allow running manually
   workflow_dispatch:
+
+concurrency:
+  # Cancel existing job(s) for workflow when a new one is queued
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
 jobs:
   ruff:
     runs-on: ubuntu-latest

.github/workflows/sphinx-docs-coverage.yml

@@ -0,0 +1,48 @@
+name: sphinx docs coverage
+
+on:
+  push:  # run on all branches
+  pull_request:
+    branches: [develop, main]
+
+permissions:
+  contents: read
+
+concurrency:
+  # Cancel existing job(s) for workflow when a new one is queued
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+env:
+  # Python version used to build sphinx docs
+  DOCS_PYTHON_VERSION: "3.12"
+
+jobs:
+  docs:
+    name: Sphinx documentation
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+
+      - name: Install uv and Python version
+        uses: astral-sh/setup-uv@v7
+        with:
+          python-version: ${{ env.DOCS_PYTHON_VERSION }}
+
+      - name: Install package dependencies
+        run: uv sync --extra docs
+
+      - name: Build Sphinx docs
+        run: cd sphinx-docs && uv run make -b coverage html
+
+      # For pull requests, exit with error if documentation coverage is incomplete
+      - name: Report on documentation coverage
+        if: github.event_name == 'pull_request'
+        run: |
+          cd sphinx-docs/_build/coverage &&
+          if [[ $((`grep corppa python.txt | grep -v 100 | wc -l`)) -eq 0 ]]; then
+            echo "Documentation coverage complete"
+          else
+            cat python.txt
+          fi

.github/workflows/unit_tests.yml

@@ -1,20 +1,25 @@
 name: unit tests
 
 on:
-  push: # run on all branches
+  push:  # run on all branches
   pull_request:
     branches: [develop, main]
-  schedule: # run automatically on main branch each Tuesday at 11am
+  schedule:  # run automatically on main branch each Tuesday at 11am
     - cron: "0 16 * * 2"
 
+concurrency:
+  # Cancel existing job(s) for workflow when a new one is queued
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
 jobs:
   python-unit:
     name: Python unit tests
     runs-on: ubuntu-latest
     strategy:
       matrix:
         python: ["3.10", "3.11", "3.12", "3.13", "3.14"]
-        django: [0, "3.2", "4.0", "4.1", "4.2", "5.0"]
+        django: [0, "5.2", "6.0"]
     steps:
       - name: Checkout repository
         uses: actions/checkout@v6

.pre-commit-config.yaml

@@ -9,9 +9,17 @@ repos:
     hooks:
       # Run the linter
       - id: ruff-check
-        args: [--fix, --show-fixes] # enable lint fixes
+        args: [--fix, --show-fixes]  # enable lint fixes
       # Run the formatter
       - id: ruff-format
+  # mdformat for formatting Markdown files
+  - repo: https://github.com/hukkin/mdformat
+    rev: 1.0.0
+    hooks:
+      - id: mdformat
+        # Optionally add plugins
+        additional_dependencies:
+          - mdformat-pyproject  # support configuration in pyproject.toml
   # yamlfmt for formatting YAML files
   - repo: https://github.com/google/yamlfmt
     rev: v0.17.2

CHANGELOG.md

@@ -0,0 +1,56 @@
+# CHANGELOG
+
+## 0.5
+
+- Now supports Python 3.10 through 3.14; drops support for Python 3.9
+- Now supports Django 5.2 and 6.0; drops support for Django 3.2 through 5.0
+- Adopt a new set of ruff linter rules
+- Add GitHub Action for ruff lint and format checks
+- Add GitHub Action to check for changelog updates
+- Add GitHub Action for checking documentation coverage
+- Add pre-commit hooks for development
+- Switch to using uv for package development
+- Switch project organization to src layout
+- Switch from os.path to pathlib
+- Switch from rst to md for documentation format
+
+## 0.4
+
+- Updates for new VIAF /search API endpoint response
+- bugfix: VIAF entity request needs Accept header
+
+## 0.3
+
+- Handle negative years when parsing birth and death dates
+- Now tested on python 3.9 through 3.12
+- Now tested against Django 3.2 through 5.0
+- Migrate continuous integration to GitHub Actions
+
+## 0.2
+
+- Now supports Django versions 1.11 through 3.0.
+
+## 0.1.4
+
+- Fix Travis-CI build for building with and without Django.
+
+## 0.1.3
+
+- Fix GitHub repository name in sphinx documentation config file.
+
+## 0.1.2
+
+- Update sphinx configuration to support building documentation on readthedocs.org
+
+## 0.1.1
+
+- Document permissions.
+
+## 0.1
+
+Initial release.
+
+- Basic support for VIAP API use: autocomplete, SRU search, information
+  about a single VIAF entity.
+- Basic Django integration (optional); django-autocomplete-light lookup
+  view and a VIAF url widget.