Merge pull request #309 from WMD-group/docs_updates

[WIP] Documentation overhaul

.github/pull_request_template.md

@@ -23,16 +23,15 @@ Please describe the tests that you ran to verify your changes. Provide instructi
 - [ ] Test B
 
 **Test Configuration**:
-* Python version:
-* Operating System:
 
+- Python version:
+- Operating System:
 
 ## Reviewers
 
 @mention individuals who you specifically want to involve in the discussion for this pull request and mention why they are needed in the discussion/why they are needed to review the pull request.
 
-
-## Checklist:
+## Checklist
 
 - [ ] My code follows the style guidelines of this project
 - [ ] I have performed a self-review of my own code

.github/release.yml

@@ -25,4 +25,4 @@ changelog:
     - title: 🏥 Package Health
       labels: [pkg]
     - title: 🤷‍♂️ Other Changes
-      labels: ["*"]
+      labels: ["*"]

.github/workflows/ci.yml

@@ -7,7 +7,6 @@ on:
       - master
 
 jobs:
-
   qa:
     runs-on: ubuntu-latest
     steps:
@@ -19,31 +18,28 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python-version: ["3.9","3.10","3.11","3.12"]
-        os: [ubuntu-latest,macos-latest,windows-latest]
-    
+        python-version: ["3.9", "3.10", "3.11", "3.12"]
+        os: [ubuntu-latest, macos-latest, windows-latest]
+
     runs-on: ${{matrix.os}}
     steps:
-    - uses: actions/checkout@v4
-    - name: Set up Python ${{ matrix.python-version }}
-      uses: actions/setup-python@v5
-      with:
-        python-version: ${{ matrix.python-version }}
-    - name: Install dependencies
-      run: |
-        python -m pip install --upgrade pip wheel setuptools
-        pip install -e .
-        pip install pytest-cov
-    - name: Run tests and collect coverage
-      run: python -m pytest --cov=smact --cov-report=xml -v
-    - name: Upload coverage reports to CodeCov
-      uses: codecov/codecov-action@v4
-      with:
-        token: ${{ secrets.CODECOV_TOKEN }}
-        #files: ./coverage.xml
-        fail_ci_if_error: False
-        env_vars: OS,PYTHON
-        verbose: true
-
-
-
+      - uses: actions/checkout@v4
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip wheel setuptools
+          pip install -e .
+          pip install pytest-cov
+      - name: Run tests and collect coverage
+        run: python -m pytest --cov=smact --cov-report=xml -v
+      - name: Upload coverage reports to CodeCov
+        uses: codecov/codecov-action@v4
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+          #files: ./coverage.xml
+          fail_ci_if_error: False
+          env_vars: OS,PYTHON
+          verbose: true

.github/workflows/combine-prs.yml

@@ -1,25 +1,25 @@
-name: 'Combine PRs'
+name: "Combine PRs"
 
 # Controls when the action will run - in this case triggered manually
 on:
   workflow_dispatch:
     inputs:
       branchPrefix:
-        description: 'Branch prefix to find combinable PRs based on'
+        description: "Branch prefix to find combinable PRs based on"
         required: true
-        default: 'dependabot'
+        default: "dependabot"
       mustBeGreen:
-        description: 'Only combine PRs that are green (status is success)'
+        description: "Only combine PRs that are green (status is success)"
         required: true
         default: true
       combineBranchName:
-        description: 'Name of the branch to combine PRs into'
+        description: "Name of the branch to combine PRs into"
         required: true
-        default: 'combine-prs-branch'
+        default: "combine-prs-branch"
       ignoreLabel:
-        description: 'Exclude PRs with this label'
+        description: "Exclude PRs with this label"
         required: true
-        default: 'nocombine'
+        default: "nocombine"
 
 # A workflow run is made up of one or more jobs that can run sequentially or in parallel
 jobs:
@@ -115,7 +115,7 @@ jobs:
               core.setFailed('Failed to create combined branch - maybe a branch by that name already exists?');
               return;
             }
-            
+
             let combinedPRs = [];
             let mergeFailedPRs = [];
             for(const { branch, prString } of branchesAndPRStrings) {
@@ -133,7 +133,7 @@ jobs:
                 mergeFailedPRs.push(prString);
               }
             }
-            
+
             console.log('Creating combined PR');
             const combinedPRsString = combinedPRs.join('\n');
             let body = '✅ This PR was created by the Combine PRs action by combining the following PRs:\n' + combinedPRsString;
@@ -148,4 +148,4 @@ jobs:
               head: '${{ github.event.inputs.combineBranchName }}',
               base: baseBranch,
               body: body
-            });
+            });

.github/workflows/publish-to-pypi.yml

@@ -3,7 +3,7 @@ name: Publish SMACT distributions to PyPI
 on:
   push:
     tags:
-      - 'v*'
+      - "v*"
 
 jobs:
   build-n-publish:

.gitignore

@@ -224,4 +224,4 @@ $RECYCLE.BIN/
 
 *.swp
 
-*.bak
+*.bak

.pre-commit-config.yaml

@@ -1,23 +1,67 @@
 repos:
-  - repo: https://github.com/timothycrosley/isort
-    rev: "5.12.0"
-    hooks:
-      - id: isort
-        additional_dependencies: [toml]
-        args: ["--profile", "black", "--filter-files", "--line-length=80"]
-  - repo: https://github.com/psf/black
-    rev: "23.1.0"
-    hooks:
-      - id: black-jupyter
-        args: [--line-length=80]
-  - repo: https://github.com/asottile/pyupgrade
-    rev: v3.3.1
-    hooks:
-      - id: pyupgrade
-        args: [--py38-plus]
-  - repo: https://github.com/nbQA-dev/nbQA
-    rev: "1.8.7"
-    hooks:
-      - id: nbqa-pyupgrade
-        additional_dependencies: [pyupgrade==3.3.1]
-        args: [--py39-plus]
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.6.1
+    hooks:
+      # Run the linting tool
+      - id: ruff
+        types_or: [python, pyi]
+        args: [--fix]
+        # Run the formatter
+      - id: ruff-format
+        types_or: [python, pyi] # TODO: Fix notebooks to remove this
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.6.0
+    hooks:
+      - id: check-yaml
+      - id: end-of-file-fixer
+      - id: trailing-whitespace
+  - repo: https://github.com/igorshubovych/markdownlint-cli
+    rev: v0.41.0
+    hooks:
+      - id: markdownlint
+        # MD013: line too long
+        # MD024: Multiple headings with the same content
+        # MD033: no inline HTML
+        # MD041: first line in a file should be a top-level heading
+        # MD025: single title
+        args:
+          [
+            --ignore,
+            "dev_docs/design_docs/*",
+            --disable,
+            MD013,
+            MD024,
+            MD025,
+            MD033,
+            MD041,
+            "--",
+          ]
+  - repo: https://github.com/pre-commit/mirrors-prettier
+    rev: v4.0.0-alpha.8
+    hooks:
+      - id: prettier
+        args: [--write] # edit files in-place
+        additional_dependencies:
+          - prettier
+  - repo: https://github.com/kynan/nbstripout
+    rev: 0.7.1
+    hooks:
+      - id: nbstripout
+        args: [--drop-empty-cells, --keep-output]
+  - repo: https://github.com/codespell-project/codespell
+    rev: v2.3.0
+    hooks:
+      - id: codespell
+        stages: [commit, commit-msg]
+        args: [--toml, pyproject.toml]
+        additional_dependencies:
+          - tomli
+  - repo: https://github.com/RobertCraigie/pyright-python
+    rev: v1.1.376
+    hooks:
+      - id: pyright
+        args: [--level, error]
+  - repo: https://github.com/adamchainz/blacken-docs
+    rev: 1.18.0
+    hooks:
+      - id: blacken-docs

.readthedocs.yaml

@@ -1,15 +1,15 @@
 version: 2
 
 build:
-  os: "ubuntu-20.04"
+  os: "ubuntu-22.04"
   tools:
-    python: "3.8"
+    python: "3.10"
 
 # Build documentation in the docs/ directory with Sphinx
 sphinx:
-   configuration: docs/conf.py
+  configuration: docs/conf.py
 
 # Explicitly set the version of Python and its requirements
 python:
   install:
-    - requirements: docs/requirements.txt
+    - requirements: docs/requirements.txt

CONTRIBUTING.md

@@ -4,7 +4,7 @@ This is a quick guide on how to follow best practice and contribute smoothly to
 
 ## Workflow
 
-We follow the [GitHub flow](<https://docs.github.com/en/get-started/using-github/github-flow>), using
+We follow the [GitHub flow](https://docs.github.com/en/get-started/using-github/github-flow), using
 branches for new work and pull requests for verifying the work.
 
 The steps for a new piece of work can be summarised as follows: