Skip to content

Commit 1648dab

Browse files
tonywu1999tonywu1999
authored
add weekly readme updater (#78)
1 parent 094c3f7 commit 1648dab

3 files changed

Lines changed: 293 additions & 0 deletions

File tree

‎.github/scripts/extract_exports.py‎

Lines changed: 105 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,105 @@
1+
"""
2+
.github/scripts/extract_exports.py
3+
4+
Walks R/, finds every function tagged with @export, and extracts its full
5+
roxygen2 documentation block. Outputs a JSON blob to GITHUB_OUTPUT so that
6+
upgrade_readme.py can consume it without re-parsing the R files.
7+
8+
Also deterministically picks a section focus for this week based on the
9+
ISO week number, so the README improves a different area each week in rotation.
10+
"""
11+
12+
import os
13+
import re
14+
import sys
15+
import json
16+
from datetime import date
17+
18+
SEARCH_DIR = "R"
19+
20+
SECTION_ROTATION = [
21+
"Getting Started / Installation",
22+
"Usage Examples",
23+
"Function Reference Table",
24+
"Motivation & Use Cases",
25+
"FAQ / Common Pitfalls",
26+
"Contributing & Development Setup",
27+
]
28+
29+
30+
def extract_function_docs(filepath: str) -> list[dict]:
31+
"""
32+
Returns a list of dicts, one per @export-tagged function:
33+
{ "name": str, "file": str, "roxygen": str }
34+
"""
35+
with open(filepath, "r", errors="ignore") as f:
36+
lines = f.readlines()
37+
38+
results = []
39+
for i, line in enumerate(lines):
40+
m = re.match(r"^(\w+)\s*(?:<-|=)\s*function\s*\(", line)
41+
if not m:
42+
continue
43+
fn_name = m.group(1)
44+
45+
# Collect the contiguous roxygen2 block above this line
46+
roxygen_lines = []
47+
j = i - 1
48+
while j >= 0 and re.match(r"^#'", lines[j]):
49+
roxygen_lines.insert(0, lines[j].rstrip())
50+
j -= 1
51+
52+
if any("@export" in l for l in roxygen_lines):
53+
results.append({
54+
"name": fn_name,
55+
"file": filepath,
56+
"roxygen": "\n".join(roxygen_lines),
57+
})
58+
59+
return results
60+
61+
62+
def main():
63+
all_exports = []
64+
65+
for root, _dirs, files in os.walk(SEARCH_DIR):
66+
for fname in sorted(files):
67+
if not fname.endswith(".R"):
68+
continue
69+
fpath = os.path.join(root, fname)
70+
try:
71+
all_exports.extend(extract_function_docs(fpath))
72+
except Exception as e:
73+
print(f"⚠️ Skipping {fpath}: {e}", file=sys.stderr)
74+
75+
if not all_exports:
76+
print(
77+
"❌ No @export-tagged functions found in R/.\n"
78+
" Add #' @export above your exported function definitions.",
79+
file=sys.stderr,
80+
)
81+
sys.exit(1)
82+
83+
print(f"✅ Found {len(all_exports)} exported functions:")
84+
for exp in all_exports:
85+
print(f" • {exp['name']} ({exp['file']})")
86+
87+
# Rotate section focus by ISO week number so it's deterministic
88+
week_number = date.today().isocalendar().week
89+
section_focus = SECTION_ROTATION[week_number % len(SECTION_ROTATION)]
90+
print(f"\n📌 This week's README focus: {section_focus}")
91+
92+
exports_json = json.dumps(all_exports)
93+
94+
github_output = os.environ.get("GITHUB_OUTPUT")
95+
if github_output:
96+
with open(github_output, "a") as fh:
97+
fh.write(f"exports_json={exports_json}\n")
98+
fh.write(f"section_focus={section_focus}\n")
99+
else:
100+
print(f"\nEXPORTS_JSON={exports_json}")
101+
print(f"SECTION_FOCUS={section_focus}")
102+
103+
104+
if __name__ == "__main__":
105+
main()

‎.github/scripts/upgrade_readme.py‎

Lines changed: 106 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,106 @@
1+
"""
2+
.github/scripts/upgrade_readme.py
3+
4+
Reads the current README.md and the full list of exported functions (from
5+
EXPORTS_JSON), then asks the AI to make one focused, cohesive improvement
6+
to the README based on the week's section focus.
7+
8+
Required environment variables:
9+
OPENAI_API_KEY - your OpenAI secret key
10+
EXPORTS_JSON - JSON string produced by extract_exports.py
11+
"""
12+
13+
import os
14+
import sys
15+
import json
16+
from openai import OpenAI
17+
18+
README_PATH = "README.md"
19+
20+
PROMPT_TEMPLATE = """\
21+
You are a technical writer helping improve the README for an R package.
22+
23+
## Current README
24+
25+
```markdown
26+
{readme_content}
27+
```
28+
29+
## Exported Functions
30+
31+
Below are all the exported functions in this package, along with their \
32+
current roxygen2 documentation:
33+
34+
{exports_block}
35+
36+
## Your Task
37+
38+
Make a single, cohesive improvement to the README focused on: **{section_focus}**
39+
40+
Guidelines:
41+
- Improve or add the "{section_focus}" section using the exported functions above as your source of truth.
42+
- Write clean, idiomatic R code examples that actually work.
43+
- Keep the tone friendly and practical — help someone get up and running quickly.
44+
- Do not remove or substantially alter any existing sections outside your focus area.
45+
- Do not add placeholder text like "coming soon" or "TODO".
46+
- Return ONLY the full updated README.md contents, with no explanation or markdown fences around it.
47+
"""
48+
49+
50+
def format_exports_block(exports: list[dict]) -> str:
51+
blocks = []
52+
for exp in exports:
53+
blocks.append(f"### `{exp['name']}` ({exp['file']})\n\n{exp['roxygen']}")
54+
return "\n\n---\n\n".join(blocks)
55+
56+
57+
def main():
58+
api_key = os.environ.get("OPENAI_API_KEY")
59+
exports_json = os.environ.get("EXPORTS_JSON")
60+
61+
missing = [k for k, v in {
62+
"OPENAI_API_KEY": api_key,
63+
"EXPORTS_JSON": exports_json,
64+
}.items() if not v]
65+
66+
if missing:
67+
print(f"❌ Missing required environment variables: {', '.join(missing)}", file=sys.stderr)
68+
sys.exit(1)
69+
70+
exports = json.loads(exports_json)
71+
section_focus = os.environ.get("SECTION_FOCUS", "Usage Examples")
72+
73+
if not os.path.exists(README_PATH):
74+
print(f"❌ {README_PATH} not found in repo root.", file=sys.stderr)
75+
sys.exit(1)
76+
77+
with open(README_PATH, "r") as f:
78+
readme_content = f.read()
79+
80+
exports_block = format_exports_block(exports)
81+
82+
prompt = PROMPT_TEMPLATE.format(
83+
readme_content=readme_content,
84+
exports_block=exports_block,
85+
section_focus=section_focus,
86+
)
87+
88+
client = OpenAI(api_key=api_key)
89+
print(f"⏳ Calling OpenAI to improve README (focus: {section_focus}) ...")
90+
91+
response = client.chat.completions.create(
92+
model="gpt-4o",
93+
messages=[{"role": "user", "content": prompt}],
94+
temperature=0.4,
95+
)
96+
97+
updated_readme = response.choices[0].message.content.strip()
98+
99+
with open(README_PATH, "w") as f:
100+
f.write(updated_readme)
101+
102+
print(f"✅ README updated successfully.")
103+
104+
105+
if __name__ == "__main__":
106+
main()

‎.github/workflows/weekly-readme-upgrade.yml‎

Lines changed: 82 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,82 @@
1+
# .github/workflows/weekly-readme-upgrade.yml
2+
#
3+
# Runs every week, reads all exported R functions + their roxygen2 docs,
4+
# and asks the AI to make one cohesive improvement to the README.
5+
# Each week it rotates focus: examples, getting started, function reference, etc.
6+
#
7+
# SETUP: Same prerequisites as weekly-doc-upgrade.yml
8+
# - MSSTATS_OPENAI_KEY secret
9+
# - Actions read/write permissions
10+
11+
name: Weekly README Upgrade
12+
13+
on:
14+
schedule:
15+
- cron: '0 9 * * 2' # Every Tuesday at 9am UTC (day after the roxygen2 job)
16+
workflow_dispatch:
17+
18+
jobs:
19+
readme-upgrade:
20+
runs-on: ubuntu-latest
21+
22+
steps:
23+
- name: Checkout repo
24+
uses: actions/checkout@v4
25+
26+
- name: Set up Python
27+
uses: actions/setup-python@v5
28+
with:
29+
python-version: '3.11'
30+
31+
- name: Install dependencies
32+
run: pip install openai
33+
34+
- name: Extract exported functions
35+
id: extract
36+
run: python3 .github/scripts/extract_exports.py
37+
38+
- name: Upgrade README with AI
39+
env:
40+
OPENAI_API_KEY: ${{ secrets.MSSTATS_OPENAI_KEY }}
41+
EXPORTS_JSON: ${{ steps.extract.outputs.exports_json }}
42+
run: python3 .github/scripts/upgrade_readme.py
43+
44+
- name: Create branch and commit
45+
run: |
46+
BRANCH="ai-docs/readme-$(date +%Y-%m-%d)"
47+
echo "BRANCH=$BRANCH" >> $GITHUB_ENV
48+
49+
git config user.name "github-actions[bot]"
50+
git config user.email "github-actions[bot]@users.noreply.github.com"
51+
52+
git checkout -b "$BRANCH"
53+
git add README.md
54+
git commit -m "docs: Weekly AI README upgrade ($(date +%Y-%m-%d))"
55+
git push origin "$BRANCH"
56+
57+
- name: Open Pull Request
58+
env:
59+
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
60+
SECTION_FOCUS: ${{ steps.extract.outputs.section_focus }}
61+
run: |
62+
gh pr create \
63+
--title "docs: Weekly AI README upgrade — ${SECTION_FOCUS}" \
64+
--body "## 🤖 Automated README Upgrade
65+
66+
This PR was auto-generated by the weekly README upgrade workflow.
67+
68+
**This week's focus:** ${SECTION_FOCUS}
69+
70+
The AI was given the full list of exported functions and their roxygen2
71+
documentation, and made a single cohesive improvement to \`README.md\`.
72+
73+
**What to check:**
74+
- [ ] The added content is accurate
75+
- [ ] Code examples actually run
76+
- [ ] The tone and style match the rest of the README
77+
- [ ] No existing content was accidentally removed
78+
79+
> Merge if it looks good. Each week the bot will focus on a different section." \
80+
--base devel \
81+
--head "$BRANCH" \
82+
--label "documentation"

0 commit comments

Comments
 (0)