Add markdownlint pre-commit hooks, Build PRs on readthedocs

.github/CODEOWNERS

@@ -0,0 +1,6 @@
+# CODEOWNERS — automatic review suggestions
+# https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners
+# GitHub automatically suggests dev-guide-admins as reviewers for all PRs.
+
+# Request review from dev-guide-admins team for all files
+* @lasp/dev-guide-admins

.github/workflows/docs.yml

@@ -0,0 +1,69 @@
+name: Docs Build
+
+# Fast CI error-gate: catches broken toctrees, bad references, and Sphinx
+# warnings before merge. Runs in ~2 min.
+#
+# The live browsable preview is handled by ReadTheDocs, which posts its own
+# status check ("docs/readthedocs.com") with a direct URL when a PR build
+# completes. Enable it once in the RTD dashboard:
+#   Admin → Advanced Settings → "Build pull requests for this project" ✓
+on:
+  pull_request:
+    types: [opened, synchronize, reopened, ready_for_review]
+
+env:
+  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
+
+jobs:
+  sphinx:
+    name: Build Sphinx docs
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Install Poetry
+        run: python -m pip install poetry
+
+      - name: Install dependencies
+        run: poetry install
+
+      - name: Build docs (warnings = errors)
+        id: build
+        shell: bash
+        run: |
+          set -o pipefail
+          poetry run sphinx-build -W --keep-going -n \
+            docs/source docs/source/build 2>&1 | tee /tmp/sphinx-output.txt
+
+      - name: Write job summary
+        if: always()
+        shell: bash
+        run: |
+          {
+            echo "## Sphinx Docs Build"
+            echo ""
+            if [ "${{ steps.build.outcome }}" = "success" ]; then
+              echo "### Build passed — no warnings"
+            else
+              echo "### Build failed — see warnings below"
+            fi
+            echo ""
+            echo "> **Live preview:** see the **ReadTheDocs** status check below for a"
+            echo "> clickable URL to browse the built docs directly."
+            echo ""
+            if [ -f /tmp/sphinx-output.txt ]; then
+              echo "<details><summary>Full Sphinx output</summary>"
+              echo ""
+              echo '```'
+              cat /tmp/sphinx-output.txt
+              echo '```'
+              echo ""
+              echo "</details>"
+            fi
+          } >> "$GITHUB_STEP_SUMMARY"

.github/workflows/pr-triage.yml

@@ -0,0 +1,56 @@
+name: PR Triage
+
+# Automatically request review from dev-guide-admins when a PR is ready for review.
+# Covers two cases:
+#   - PR opened directly as ready for review (opened, reopened)
+#   - Draft PR converted to ready for review (ready_for_review)
+on:
+  pull_request_target:
+    types: [opened, reopened, ready_for_review]
+
+permissions:
+  pull-requests: write
+  issues: write
+
+env:
+  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
+
+jobs:
+  triage:
+    name: Request review from triage team
+    # Skip draft PRs — only run when the PR is actually ready for review
+    if: github.event.pull_request.draft == false
+    runs-on: ubuntu-latest
+
+    steps:
+      # Request review from the dev-guide-admins team.
+      # Also posts a comment mentioning the team as a reliable fallback notification,
+      # since requestReviewers can silently fail for teams in some org configurations.
+      - name: Request review and notify dev-guide-admins
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const pr = context.payload.pull_request.number;
+            const { owner, repo } = context.repo;
+
+            // Attempt to assign the team as a formal reviewer
+            try {
+              await github.rest.pulls.requestReviewers({
+                owner,
+                repo,
+                pull_number: pr,
+                team_reviewers: ['dev-guide-admins'],
+              });
+              console.log('Successfully requested review from dev-guide-admins');
+            } catch (err) {
+              // Log the error but don't fail — the comment below still notifies the team
+              console.error('requestReviewers failed:', err.message);
+            }
+
+            // Post a comment mentioning the team so they are always notified
+            await github.rest.issues.createComment({
+              owner,
+              repo,
+              issue_number: pr,
+              body: '@lasp/dev-guide-admins — this PR is ready for review.',
+            });

.github/workflows/test.yml

@@ -1,13 +1,23 @@
 name: Dependency Check
 
+# Verifies that the Poetry dependency lock-file resolves cleanly across the
+# supported Python range. Doc building is handled by the separate docs.yml job.
 on:
   pull_request:
-    types: [opened, synchronize, edited]
+    types: [opened, synchronize, edited, reopened]
+
+# Opt into Node.js 24 for all actions in this workflow.
+# Remove once actions/checkout and actions/setup-python release
+# versions that natively target Node.js 24.
+env:
+  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
 
 jobs:
   build:
+    name: Install deps (Python ${{ matrix.python-version }}, ${{ matrix.os }})
     runs-on: ${{ matrix.os }}
     strategy:
+      fail-fast: false
       matrix:
         os: [ubuntu-latest, macos-latest]
         python-version: ['3.10', '3.11']
@@ -16,12 +26,12 @@ jobs:
         shell: bash
 
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
       - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v5
         with:
           python-version: ${{ matrix.python-version }}
-      - uses: Gr1N/setup-poetry@v8
-      - name: Install dependencies and app
-        run: |
-          poetry install
+      - name: Install Poetry
+        run: python -m pip install poetry
+      - name: Install dependencies
+        run: poetry install

.gitignore

@@ -1,3 +1,3 @@
 .idea/
 docs/source/build
-docs/build
+docs/build

.markdownlint.yaml

@@ -0,0 +1,61 @@
+# Markdownlint configuration for markdownlint-cli2 (Node.js)
+# Rule reference: https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md
+#
+# This mirrors the exclusions in .mdl_style.rb (used by the Ruby mdl gem)
+# so both tools agree. The .mdlrc / .mdl_style.rb files can be retired once
+# the team is fully on markdownlint-cli.
+
+default: true
+
+# -- Line length --------------------------------------------------------------
+# Disabled: MD013 cannot be auto-fixed by markdownlint --fix (it would require
+# editorial judgment about where to wrap prose). Enforcing it creates friction
+# for contributors and has no effect on the rendered Sphinx/HTML output.
+MD013: false
+
+# -- Disabled rules (match .mdl_style.rb exclusions) -------------------------
+MD014: false   # Dollar signs before commands without showing output — allowed
+MD029: false   # Ordered list item prefix — allow repeating "1." style
+MD033: false   # Inline HTML — allowed
+MD034: false   # Bare URLs — allowed
+MD036: false   # Emphasis used instead of a heading — allowed
+MD059: false   # Descriptive link text — "here" links can't be auto-fixed; cosmetic only
+
+# -- Additional sensible rules ------------------------------------------------
+# Enforce consistent heading style (ATX = # style, not underline style)
+MD003:
+  style: atx
+
+# Enforce consistent unordered list marker (* vs - vs +)
+MD004:
+  style: consistent
+
+# No multiple blank lines
+MD012:
+  maximum: 1
+
+# No hard tabs
+MD010:
+  spaces_per_tab: 4
+
+# Fenced code blocks should have a language specified
+MD040: true
+
+# No trailing punctuation in headings
+MD026:
+  punctuation: ".,;:!"
+
+# -- Disabled rules (repo convention) -----------------------------------------
+# The guideline template consistently uses 2-space sub-bullets under numbered
+# lists (e.g., 1. **Step** \n  - detail). Enforcing MD007 would require
+# rewriting every How-to-Apply section across the whole site.
+MD007: false
+
+# Tight lists (no blank lines between items) are idiomatic in this repo's
+# guideline pages. MD032 would require blank lines around every list block.
+MD032: false
+
+# Table column alignment style is overly strict for contributors and produces
+# false positives on wide-cell tables — disable until a consistent table style
+# is established across the whole site.
+MD060: false

.mdl_style.rb

@@ -4,4 +4,4 @@
 exclude_rule 'MD033'  # Inline HTML
 exclude_rule 'MD034'  # Bare URL used
 exclude_rule 'MD036'  # Emphasis used instead of a header
-rule 'MD013', :line_length => 120, :ignore_code_blocks => true, :tables => false
+rule 'MD013', :line_length => 120, :ignore_code_blocks => true, :tables => false

.mdlrc

@@ -1 +1 @@
-style "#{File.dirname(__FILE__)}/.mdl_style.rb"
+style "#{File.dirname(__FILE__)}/.mdl_style.rb"

.pre-commit-config.yaml

@@ -1,21 +1,86 @@
 ci:
-  autofix_prs: false
+  # pre-commit.ci (https://pre-commit.ci) — free for open-source repos.
+  # When enabled, it runs all hooks on every PR and commits any auto-fixes
+  # back to the PR branch automatically (no local setup required for contributors).
+  # Hooks that can auto-fix: end-of-file-fixer, trailing-whitespace,
+  #   mixed-line-ending, markdownlint (--fix), codespell (--write-changes).
+  # Hooks that only detect (still require a human fix): check-yaml,
+  #   check-merge-conflict, rstcheck, yamllint.
+  autofix_prs: true
   autoupdate_schedule: 'quarterly'
+  # rstcheck needs a full Sphinx/Poetry environment that pre-commit.ci
+  # doesn't have — skip it there and let docs.yml in GitHub Actions cover it.
+  skip: [rstcheck]
+
 repos:
+  # ---------------------------------------------------------------------------
+  # General file hygiene
+  # ---------------------------------------------------------------------------
   - repo: https://github.com/pre-commit/pre-commit-hooks
     rev: v5.0.0
     hooks:
-    - id: check-added-large-files
-      args: ['--maxkb=1000']
-    - id: detect-aws-credentials
-      args: [--allow-missing-credentials]
-    - id: detect-private-key
-    - id: mixed-line-ending
-    - id: trailing-whitespace
-    - id: no-commit-to-branch
-      args: [--branch, main]
+      - id: check-added-large-files   # block files > 1 MB
+        args: ['--maxkb=1000']
+      - id: check-case-conflict       # catch Mac/Windows case insensitivity bugs
+      - id: check-merge-conflict      # catch leftover <<<< ==== >>>> markers
+      - id: check-yaml                # validate all YAML files (workflows, config)
+      - id: detect-aws-credentials
+        args: [--allow-missing-credentials]
+      - id: detect-private-key
+      - id: end-of-file-fixer         # ensure every file ends with a newline
+      - id: mixed-line-ending
+      - id: no-commit-to-branch
+        args: [--branch, main]
+      - id: trailing-whitespace
+        # --markdown-linebreak-ext preserves intentional two-space line breaks in .md
+        args: [--markdown-linebreak-ext=md]
+
+  # ---------------------------------------------------------------------------
+  # Markdown linting
+  # Config: .markdownlint.yaml  (mirrors the existing .mdl_style.rb exclusions)
+  # markdownlint-cli2 is the official CLI maintained by the markdownlint author (DavidAnson).
+  # ---------------------------------------------------------------------------
+  - repo: https://github.com/DavidAnson/markdownlint-cli2
+    rev: v0.19.1
+    hooks:
+      - id: markdownlint-cli2
+        # --fix auto-corrects issues with a safe mechanical fix.
+        # Issues requiring human judgement are still reported as errors.
+        args: [--fix, --config, .markdownlint.yaml]
+
+  # ---------------------------------------------------------------------------
+  # reStructuredText validation (toctree, directives, broken references)
+  # ---------------------------------------------------------------------------
+  - repo: https://github.com/rstcheck/rstcheck
+    rev: v6.2.4
+    hooks:
+      - id: rstcheck
+        additional_dependencies: ['rstcheck-core', 'sphinx']
+        args: [--report-level=warning]
+
+  # ---------------------------------------------------------------------------
+  # YAML linting — catches style issues in workflow files and config
+  # Config: .yamllint.yaml
+  # ---------------------------------------------------------------------------
+  - repo: https://github.com/adrienverge/yamllint
+    rev: v1.35.1
+    hooks:
+      - id: yamllint
+        args: [--config-file, .yamllint.yaml]
+
+  # ---------------------------------------------------------------------------
+  # Spell checking (.md, .rst, .yml, .yaml)
+  # ---------------------------------------------------------------------------
   - repo: https://github.com/codespell-project/codespell
     rev: v2.4.1
     hooks:
       - id: codespell
-        files: ^.*\.(md|rst|yml)$
+        files: ^.*\.(md|rst|ya?ml)$
+        args:
+          # --write-changes auto-corrects unambiguous spelling mistakes.
+          # Ambiguous corrections (multiple candidates) are still reported.
+          - --write-changes
+          # nd/ND = Creative Commons "No Derivatives"
+          # SORCE = Solar Radiation and Climate Experiment (NASA mission)
+          # sav = IDL save file extension
+          - --ignore-words-list=nd,ND,SORCE,sav

.readthedocs.yaml

@@ -7,16 +7,16 @@ version: 2
 build:
   os: "ubuntu-22.04"
   tools:
-    python: "3.10"
+    python: "3.11"
   jobs:
     post_create_environment:
       # Install poetry
       # https://python-poetry.org/docs/#installing-manually
       - python -m pip install poetry
     post_install:
-      # Install dependencies with 'docs' dependency group
-      # https://python-poetry.org/docs/managing-dependencies/#dependency-groups
+      # Install dependencies with Poetry
       - VIRTUAL_ENV=$READTHEDOCS_VIRTUALENV_PATH poetry install
 
 sphinx:
-  configuration: docs/source/conf.py
+  configuration: docs/source/conf.py
+  fail_on_warning: true