Skip to content

Commit da92d11

Browse files
mmaclayCopilot
mmaclay
and
Copilot
authored
pre-commit hooks for markdown, sphinx build, readthedocs build, auto assign PRs to admin team
* Add GitHub Actions for Sphinx documentation build and update dependency check workflow * Update documentation formatting and ensure all pages listed in toctree * Add markdownlint and yamllint configurations for consistent linting * Update .gitignore to include docs/build directory * Refactor documentation for markdownlint * Update codespell ignore-words-list with explanations for clarity * Fix missing newline at end of file in conf.py * Remove unnecessary blank lines in docs.yml * Add missing newlines at the end of files in index.rst * Add missing newline at end of LICENSE file * Update codespell ignore-words-list with additional comments for clarity * Enable autofix for pre-commit.ci and update markdownlint and codespell configurations * Remove missing section in index * Opt into Node.js 24 for all actions in the workflow * Opt into Node.js 24 for all actions in the workflow * Add fail_on_warning to ReadTheDocs configuration and enhance Sphinx build output summary * Remove empty jenkins_job_builder section from index * update comment Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * include yaml in lint Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * Update README.md to enhance contributing guidelines and clarify documentation structure * Refine Sphinx Docs Build output formatting for clarity * Add CODEOWNERS file and PR triage workflow for automatic review requests to admins * Simplify post_install comment in .readthedocs.yaml for clarity * Fix typo in code of conduct regarding reporting violations * Add conditional check for Sphinx output in GitHub step summary * Fix typos in pull_requests.md for clarity and correctness * Update markdownlint configuration to use markdownlint-cli2 and adjust rules * Improve clarity in Docker documentation by updating links and phrasing * Enhance PR triage workflow by expanding review request triggers and adding fallback notifications * orchid typo Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * stop line length linting since it doesn't have auto fix * allow "here" links * readthedocs python 311 --------- Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
1 parent d08c2f5 commit da92d11

37 files changed

Lines changed: 619 additions & 199 deletions

‎.github/CODEOWNERS‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
# CODEOWNERS — automatic review suggestions
2+
# https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners
3+
# GitHub automatically suggests dev-guide-admins as reviewers for all PRs.
4+
5+
# Request review from dev-guide-admins team for all files
6+
* @lasp/dev-guide-admins

‎.github/workflows/docs.yml‎

Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,69 @@
1+
name: Docs Build
2+
3+
# Fast CI error-gate: catches broken toctrees, bad references, and Sphinx
4+
# warnings before merge. Runs in ~2 min.
5+
#
6+
# The live browsable preview is handled by ReadTheDocs, which posts its own
7+
# status check ("docs/readthedocs.com") with a direct URL when a PR build
8+
# completes. Enable it once in the RTD dashboard:
9+
# Admin → Advanced Settings → "Build pull requests for this project" ✓
10+
on:
11+
pull_request:
12+
types: [opened, synchronize, reopened, ready_for_review]
13+
14+
env:
15+
FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
16+
17+
jobs:
18+
sphinx:
19+
name: Build Sphinx docs
20+
runs-on: ubuntu-latest
21+
22+
steps:
23+
- uses: actions/checkout@v4
24+
25+
- name: Set up Python
26+
uses: actions/setup-python@v5
27+
with:
28+
python-version: '3.11'
29+
30+
- name: Install Poetry
31+
run: python -m pip install poetry
32+
33+
- name: Install dependencies
34+
run: poetry install
35+
36+
- name: Build docs (warnings = errors)
37+
id: build
38+
shell: bash
39+
run: |
40+
set -o pipefail
41+
poetry run sphinx-build -W --keep-going -n \
42+
docs/source docs/source/build 2>&1 | tee /tmp/sphinx-output.txt
43+
44+
- name: Write job summary
45+
if: always()
46+
shell: bash
47+
run: |
48+
{
49+
echo "## Sphinx Docs Build"
50+
echo ""
51+
if [ "${{ steps.build.outcome }}" = "success" ]; then
52+
echo "### Build passed — no warnings"
53+
else
54+
echo "### Build failed — see warnings below"
55+
fi
56+
echo ""
57+
echo "> **Live preview:** see the **ReadTheDocs** status check below for a"
58+
echo "> clickable URL to browse the built docs directly."
59+
echo ""
60+
if [ -f /tmp/sphinx-output.txt ]; then
61+
echo "<details><summary>Full Sphinx output</summary>"
62+
echo ""
63+
echo '```'
64+
cat /tmp/sphinx-output.txt
65+
echo '```'
66+
echo ""
67+
echo "</details>"
68+
fi
69+
} >> "$GITHUB_STEP_SUMMARY"

‎.github/workflows/pr-triage.yml‎

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
name: PR Triage
2+
3+
# Automatically request review from dev-guide-admins when a PR is ready for review.
4+
# Covers two cases:
5+
# - PR opened directly as ready for review (opened, reopened)
6+
# - Draft PR converted to ready for review (ready_for_review)
7+
on:
8+
pull_request_target:
9+
types: [opened, reopened, ready_for_review]
10+
11+
permissions:
12+
pull-requests: write
13+
issues: write
14+
15+
env:
16+
FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
17+
18+
jobs:
19+
triage:
20+
name: Request review from triage team
21+
# Skip draft PRs — only run when the PR is actually ready for review
22+
if: github.event.pull_request.draft == false
23+
runs-on: ubuntu-latest
24+
25+
steps:
26+
# Request review from the dev-guide-admins team.
27+
# Also posts a comment mentioning the team as a reliable fallback notification,
28+
# since requestReviewers can silently fail for teams in some org configurations.
29+
- name: Request review and notify dev-guide-admins
30+
uses: actions/github-script@v7
31+
with:
32+
script: |
33+
const pr = context.payload.pull_request.number;
34+
const { owner, repo } = context.repo;
35+
36+
// Attempt to assign the team as a formal reviewer
37+
try {
38+
await github.rest.pulls.requestReviewers({
39+
owner,
40+
repo,
41+
pull_number: pr,
42+
team_reviewers: ['dev-guide-admins'],
43+
});
44+
console.log('Successfully requested review from dev-guide-admins');
45+
} catch (err) {
46+
// Log the error but don't fail — the comment below still notifies the team
47+
console.error('requestReviewers failed:', err.message);
48+
}
49+
50+
// Post a comment mentioning the team so they are always notified
51+
await github.rest.issues.createComment({
52+
owner,
53+
repo,
54+
issue_number: pr,
55+
body: '@lasp/dev-guide-admins — this PR is ready for review.',
56+
});

‎.github/workflows/test.yml‎

Lines changed: 17 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,23 @@
11
name: Dependency Check
22

3+
# Verifies that the Poetry dependency lock-file resolves cleanly across the
4+
# supported Python range. Doc building is handled by the separate docs.yml job.
35
on:
46
pull_request:
5-
types: [opened, synchronize, edited]
7+
types: [opened, synchronize, edited, reopened]
8+
9+
# Opt into Node.js 24 for all actions in this workflow.
10+
# Remove once actions/checkout and actions/setup-python release
11+
# versions that natively target Node.js 24.
12+
env:
13+
FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
614

715
jobs:
816
build:
17+
name: Install deps (Python ${{ matrix.python-version }}, ${{ matrix.os }})
918
runs-on: ${{ matrix.os }}
1019
strategy:
20+
fail-fast: false
1121
matrix:
1222
os: [ubuntu-latest, macos-latest]
1323
python-version: ['3.10', '3.11']
@@ -16,12 +26,12 @@ jobs:
1626
shell: bash
1727

1828
steps:
19-
- uses: actions/checkout@v3
29+
- uses: actions/checkout@v4
2030
- name: Set up Python ${{ matrix.python-version }}
21-
uses: actions/setup-python@v4
31+
uses: actions/setup-python@v5
2232
with:
2333
python-version: ${{ matrix.python-version }}
24-
- uses: Gr1N/setup-poetry@v8
25-
- name: Install dependencies and app
26-
run: |
27-
poetry install
34+
- name: Install Poetry
35+
run: python -m pip install poetry
36+
- name: Install dependencies
37+
run: poetry install

‎.gitignore‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,3 @@
11
.idea/
22
docs/source/build
3-
docs/build
3+
docs/build

‎.markdownlint.yaml‎

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
# Markdownlint configuration for markdownlint-cli2 (Node.js)
2+
# Rule reference: https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md
3+
#
4+
# This mirrors the exclusions in .mdl_style.rb (used by the Ruby mdl gem)
5+
# so both tools agree. The .mdlrc / .mdl_style.rb files can be retired once
6+
# the team is fully on markdownlint-cli.
7+
8+
default: true
9+
10+
# -- Line length --------------------------------------------------------------
11+
# Disabled: MD013 cannot be auto-fixed by markdownlint --fix (it would require
12+
# editorial judgment about where to wrap prose). Enforcing it creates friction
13+
# for contributors and has no effect on the rendered Sphinx/HTML output.
14+
MD013: false
15+
16+
# -- Disabled rules (match .mdl_style.rb exclusions) -------------------------
17+
MD014: false # Dollar signs before commands without showing output — allowed
18+
MD029: false # Ordered list item prefix — allow repeating "1." style
19+
MD033: false # Inline HTML — allowed
20+
MD034: false # Bare URLs — allowed
21+
MD036: false # Emphasis used instead of a heading — allowed
22+
MD059: false # Descriptive link text — "here" links can't be auto-fixed; cosmetic only
23+
24+
# -- Additional sensible rules ------------------------------------------------
25+
# Enforce consistent heading style (ATX = # style, not underline style)
26+
MD003:
27+
style: atx
28+
29+
# Enforce consistent unordered list marker (* vs - vs +)
30+
MD004:
31+
style: consistent
32+
33+
# No multiple blank lines
34+
MD012:
35+
maximum: 1
36+
37+
# No hard tabs
38+
MD010:
39+
spaces_per_tab: 4
40+
41+
# Fenced code blocks should have a language specified
42+
MD040: true
43+
44+
# No trailing punctuation in headings
45+
MD026:
46+
punctuation: ".,;:!"
47+
48+
# -- Disabled rules (repo convention) -----------------------------------------
49+
# The guideline template consistently uses 2-space sub-bullets under numbered
50+
# lists (e.g., 1. **Step** \n - detail). Enforcing MD007 would require
51+
# rewriting every How-to-Apply section across the whole site.
52+
MD007: false
53+
54+
# Tight lists (no blank lines between items) are idiomatic in this repo's
55+
# guideline pages. MD032 would require blank lines around every list block.
56+
MD032: false
57+
58+
# Table column alignment style is overly strict for contributors and produces
59+
# false positives on wide-cell tables — disable until a consistent table style
60+
# is established across the whole site.
61+
MD060: false

‎.mdl_style.rb‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,4 +4,4 @@
44
exclude_rule 'MD033' # Inline HTML
55
exclude_rule 'MD034' # Bare URL used
66
exclude_rule 'MD036' # Emphasis used instead of a header
7-
rule 'MD013', :line_length => 120, :ignore_code_blocks => true, :tables => false
7+
rule 'MD013', :line_length => 120, :ignore_code_blocks => true, :tables => false

‎.mdlrc‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1 @@
1-
style "#{File.dirname(__FILE__)}/.mdl_style.rb"
1+
style "#{File.dirname(__FILE__)}/.mdl_style.rb"

‎.pre-commit-config.yaml‎

Lines changed: 76 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -1,21 +1,86 @@
11
ci:
2-
autofix_prs: false
2+
# pre-commit.ci (https://pre-commit.ci) — free for open-source repos.
3+
# When enabled, it runs all hooks on every PR and commits any auto-fixes
4+
# back to the PR branch automatically (no local setup required for contributors).
5+
# Hooks that can auto-fix: end-of-file-fixer, trailing-whitespace,
6+
# mixed-line-ending, markdownlint (--fix), codespell (--write-changes).
7+
# Hooks that only detect (still require a human fix): check-yaml,
8+
# check-merge-conflict, rstcheck, yamllint.
9+
autofix_prs: true
310
autoupdate_schedule: 'quarterly'
11+
# rstcheck needs a full Sphinx/Poetry environment that pre-commit.ci
12+
# doesn't have — skip it there and let docs.yml in GitHub Actions cover it.
13+
skip: [rstcheck]
14+
415
repos:
16+
# ---------------------------------------------------------------------------
17+
# General file hygiene
18+
# ---------------------------------------------------------------------------
519
- repo: https://github.com/pre-commit/pre-commit-hooks
620
rev: v5.0.0
721
hooks:
8-
- id: check-added-large-files
9-
args: ['--maxkb=1000']
10-
- id: detect-aws-credentials
11-
args: [--allow-missing-credentials]
12-
- id: detect-private-key
13-
- id: mixed-line-ending
14-
- id: trailing-whitespace
15-
- id: no-commit-to-branch
16-
args: [--branch, main]
22+
- id: check-added-large-files # block files > 1 MB
23+
args: ['--maxkb=1000']
24+
- id: check-case-conflict # catch Mac/Windows case insensitivity bugs
25+
- id: check-merge-conflict # catch leftover <<<< ==== >>>> markers
26+
- id: check-yaml # validate all YAML files (workflows, config)
27+
- id: detect-aws-credentials
28+
args: [--allow-missing-credentials]
29+
- id: detect-private-key
30+
- id: end-of-file-fixer # ensure every file ends with a newline
31+
- id: mixed-line-ending
32+
- id: no-commit-to-branch
33+
args: [--branch, main]
34+
- id: trailing-whitespace
35+
# --markdown-linebreak-ext preserves intentional two-space line breaks in .md
36+
args: [--markdown-linebreak-ext=md]
37+
38+
# ---------------------------------------------------------------------------
39+
# Markdown linting
40+
# Config: .markdownlint.yaml (mirrors the existing .mdl_style.rb exclusions)
41+
# markdownlint-cli2 is the official CLI maintained by the markdownlint author (DavidAnson).
42+
# ---------------------------------------------------------------------------
43+
- repo: https://github.com/DavidAnson/markdownlint-cli2
44+
rev: v0.19.1
45+
hooks:
46+
- id: markdownlint-cli2
47+
# --fix auto-corrects issues with a safe mechanical fix.
48+
# Issues requiring human judgement are still reported as errors.
49+
args: [--fix, --config, .markdownlint.yaml]
50+
51+
# ---------------------------------------------------------------------------
52+
# reStructuredText validation (toctree, directives, broken references)
53+
# ---------------------------------------------------------------------------
54+
- repo: https://github.com/rstcheck/rstcheck
55+
rev: v6.2.4
56+
hooks:
57+
- id: rstcheck
58+
additional_dependencies: ['rstcheck-core', 'sphinx']
59+
args: [--report-level=warning]
60+
61+
# ---------------------------------------------------------------------------
62+
# YAML linting — catches style issues in workflow files and config
63+
# Config: .yamllint.yaml
64+
# ---------------------------------------------------------------------------
65+
- repo: https://github.com/adrienverge/yamllint
66+
rev: v1.35.1
67+
hooks:
68+
- id: yamllint
69+
args: [--config-file, .yamllint.yaml]
70+
71+
# ---------------------------------------------------------------------------
72+
# Spell checking (.md, .rst, .yml, .yaml)
73+
# ---------------------------------------------------------------------------
1774
- repo: https://github.com/codespell-project/codespell
1875
rev: v2.4.1
1976
hooks:
2077
- id: codespell
21-
files: ^.*\.(md|rst|yml)$
78+
files: ^.*\.(md|rst|ya?ml)$
79+
args:
80+
# --write-changes auto-corrects unambiguous spelling mistakes.
81+
# Ambiguous corrections (multiple candidates) are still reported.
82+
- --write-changes
83+
# nd/ND = Creative Commons "No Derivatives"
84+
# SORCE = Solar Radiation and Climate Experiment (NASA mission)
85+
# sav = IDL save file extension
86+
- --ignore-words-list=nd,ND,SORCE,sav

‎.readthedocs.yaml‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -7,16 +7,16 @@ version: 2
77
build:
88
os: "ubuntu-22.04"
99
tools:
10-
python: "3.10"
10+
python: "3.11"
1111
jobs:
1212
post_create_environment:
1313
# Install poetry
1414
# https://python-poetry.org/docs/#installing-manually
1515
- python -m pip install poetry
1616
post_install:
17-
# Install dependencies with 'docs' dependency group
18-
# https://python-poetry.org/docs/managing-dependencies/#dependency-groups
17+
# Install dependencies with Poetry
1918
- VIRTUAL_ENV=$READTHEDOCS_VIRTUALENV_PATH poetry install
2019

2120
sphinx:
22-
configuration: docs/source/conf.py
21+
configuration: docs/source/conf.py
22+
fail_on_warning: true

0 commit comments

Comments
 (0)