okooooooo/opencli
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: add missing adapter docs, fix sidebar 404s, add doc-check CI (#140)

Browse Source 
* docs: add missing adapter docs, fix sidebar 404s, add doc-check CI

- Add doc pages for 11 undocumented adapters: arxiv, barchart,
  chaoxing, grok, hf, jike, jimeng, linux-do, sinafinance,
  stackoverflow, weread, wikipedia
- Update adapters/index.md with all new adapter entries
- Update VitePress sidebar config with 12 new entries
- Remove broken zh/ sidebar refs (troubleshooting, testing)
- Add doc-check CI workflow (adapter coverage + build + link check)
- Add scripts/check-doc-coverage.sh for adapter doc enforcement
- Enhance PR template with adapter doc checklist

* fix(ci): use --root-dir instead of --base for lychee link checker

lychee v0.23 requires --base to be a URL or absolute path.
Use --root-dir for resolving root-relative links in local files.

* fix(ci): remove lychee link-check job, rely on VitePress build

VitePress links use extension-less paths (e.g. /adapters/browser/twitter)
which lychee cannot resolve. The docs-build job already catches all
broken internal links via VitePress dead link detection during build.
This commit is contained in:
AlexYue authored and GitHub committed 2026-03-20 22:08:38 +08:00
1 parent 53a95ed0ce
commit 15d3583c60
17 files changed
+588 -2
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

.github/pull_request_template.md
+7
View File
@@ -19,6 +19,13 @@ Related issue:
- [ ] I updated tests or docs if needed
- [ ] I included output or screenshots when useful
### Documentation (if adding/modifying an adapter)
- [ ] Added doc page under `docs/adapters/` (if new adapter)
- [ ] Updated `docs/adapters/index.md` table (if new adapter)
- [ ] Updated sidebar in `docs/.vitepress/config.mts` (if new adapter)
## Screenshots / Output
<!-- If applicable, paste CLI output or screenshots here. -->
.github/workflows/doc-check.yml
+36
View File
@@ -0,0 +1,36 @@
name: Doc Check
on:
pull_request:
branches: [main, dev]
concurrency:
group: doc-check-${{ github.ref }}
cancel-in-progress: true
jobs:
# ── Adapter doc coverage ──
doc-coverage:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Check adapter doc coverage
run: bash scripts/check-doc-coverage.sh --strict
# ── VitePress build validation ──
docs-build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: '22'
cache: 'npm'
- name: Install dependencies
run: npm ci
- name: Build docs (catches broken links & sidebar refs)
run: npm run docs:build
docs/.vitepress/config.mts
+12 -2
View File
@@ -60,6 +60,12 @@ export default defineConfig({
{ text: 'Ctrip', link: '/adapters/browser/ctrip' },
{ text: 'Reuters', link: '/adapters/browser/reuters' },
{ text: 'SMZDM', link: '/adapters/browser/smzdm' },
{ text: 'Jike', link: '/adapters/browser/jike' },
{ text: 'Jimeng', link: '/adapters/browser/jimeng' },
{ text: 'LINUX DO', link: '/adapters/browser/linux-do' },
{ text: 'Chaoxing', link: '/adapters/browser/chaoxing' },
{ text: 'Grok', link: '/adapters/browser/grok' },
{ text: 'WeRead', link: '/adapters/browser/weread' },
],
},
{
@@ -72,6 +78,12 @@ export default defineConfig({
{ text: 'Apple Podcasts', link: '/adapters/browser/apple-podcasts' },
{ text: 'Xiaoyuzhou', link: '/adapters/browser/xiaoyuzhou' },
{ text: 'Yahoo Finance', link: '/adapters/browser/yahoo-finance' },
{ text: 'arXiv', link: '/adapters/browser/arxiv' },
{ text: 'Barchart', link: '/adapters/browser/barchart' },
{ text: 'Hugging Face', link: '/adapters/browser/hf' },
{ text: 'Sina Finance', link: '/adapters/browser/sinafinance' },
{ text: 'Stack Overflow', link: '/adapters/browser/stackoverflow' },
{ text: 'Wikipedia', link: '/adapters/browser/wikipedia' },
],
},
{
@@ -137,7 +149,6 @@ export default defineConfig({
{ text: '快速开始', link: '/zh/guide/getting-started' },
{ text: '安装', link: '/zh/guide/installation' },
{ text: 'Browser Bridge', link: '/zh/guide/browser-bridge' },
{ text: '问题排查', link: '/zh/guide/troubleshooting' },
],
},
],
@@ -154,7 +165,6 @@ export default defineConfig({
text: '开发者指南',
items: [
{ text: '贡献指南', link: '/zh/developer/contributing' },
{ text: '测试', link: '/zh/developer/testing' },
],
},
],
docs/adapters/browser/arxiv.md
+27
View File
@@ -0,0 +1,27 @@
# arXiv
**Mode**: 🌐 Public · **Domain**: `arxiv.org`
## Commands
| Command | Description |
|---------|-------------|
| `opencli arxiv search` | Search arXiv papers |
| `opencli arxiv paper` | Get arXiv paper details by ID |
## Usage Examples
```bash
# Search for papers
opencli arxiv search --query "transformer attention" --limit 10
# Get paper details by arXiv ID
opencli arxiv paper --id 2301.00001
# JSON output
opencli arxiv search --query "LLM" -f json
```
## Prerequisites
- No browser required — uses public arXiv API
docs/adapters/browser/barchart.md
+32
View File
@@ -0,0 +1,32 @@
# Barchart
**Mode**: 🌐 Public · **Domain**: `barchart.com`
## Commands
| Command | Description |
|---------|-------------|
| `opencli barchart quote` | Stock quote with price, volume, and key metrics |
| `opencli barchart options` | Options chain with greeks, IV, volume, and open interest |
| `opencli barchart greeks` | Options greeks overview (IV, delta, gamma, theta, vega) |
| `opencli barchart flow` | Unusual options activity / options flow |
## Usage Examples
```bash
# Get stock quote
opencli barchart quote --symbol AAPL
# View options chain
opencli barchart options --symbol TSLA
# Options greeks overview
opencli barchart greeks --symbol NVDA
# Unusual options flow
opencli barchart flow --limit 20 -f json
```
## Prerequisites
- No browser required — uses public API
docs/adapters/browser/chaoxing.md
+39
View File
@@ -0,0 +1,39 @@
# 超星学习通 (Chaoxing)
**Mode**: 🔐 Browser · **Domain**: `mooc2-ans.chaoxing.com`
## Commands
| Command | Description |
|---------|-------------|
| `opencli chaoxing assignments` | 学习通作业列表 |
| `opencli chaoxing exams` | 学习通考试列表 |
## Usage Examples
```bash
# List all assignments
opencli chaoxing assignments --limit 20
# Filter exams by course name
opencli chaoxing exams --course "高等数学"
# Filter exams by status
opencli chaoxing exams --status ongoing
# JSON output
opencli chaoxing assignments -f json
```
### Options
| Option | Description |
|--------|-------------|
| `--course` | Filter by course name (fuzzy match) |
| `--status` | Filter by status: `all`, `upcoming`, `ongoing`, `finished` |
| `--limit` | Max number of results (default: 20) |
## Prerequisites
- Chrome running and **logged into** mooc2-ans.chaoxing.com
- [Browser Bridge extension](/guide/browser-bridge) installed
docs/adapters/browser/grok.md
+35
View File
@@ -0,0 +1,35 @@
# Grok
**Mode**: 🔐 Browser · **Domain**: `grok.com`
## Commands
| Command | Description |
|---------|-------------|
| `opencli grok ask` | Send a message to Grok and get response |
## Usage Examples
```bash
# Ask Grok a question
opencli grok ask --prompt "Explain quantum computing in simple terms"
# Start a new chat session
opencli grok ask --prompt "Hello" --new
# Set custom timeout (default: 120s)
opencli grok ask --prompt "Write a long essay" --timeout 180
```
### Options
| Option | Description |
|--------|-------------|
| `--prompt` | The message to send (required) |
| `--timeout` | Wait timeout in seconds (default: 120) |
| `--new` | Start a new chat session (default: false) |
## Prerequisites
- Chrome running and **logged into** grok.com
- [Browser Bridge extension](/guide/browser-bridge) installed
docs/adapters/browser/hf.md
+42
View File
@@ -0,0 +1,42 @@
# Hugging Face
**Mode**: 🌐 Public · **Domain**: `huggingface.co`
## Commands
| Command | Description |
|---------|-------------|
| `opencli hf top` | Top upvoted Hugging Face papers |
## Usage Examples
```bash
# Today's top papers
opencli hf top --limit 10
# All papers (no limit)
opencli hf top --all
# Specific date
opencli hf top --date 2025-03-01
# Weekly/monthly top papers
opencli hf top --period weekly
opencli hf top --period monthly
# JSON output
opencli hf top -f json
```
### Options
| Option | Description |
|--------|-------------|
| `--limit` | Number of papers (default: 20) |
| `--all` | Return all papers, ignoring limit |
| `--date` | Date in `YYYY-MM-DD` format (defaults to most recent) |
| `--period` | Time period: `daily`, `weekly`, or `monthly` (default: daily) |
## Prerequisites
- No browser required — uses public Hugging Face API
docs/adapters/browser/jike.md
+45
View File
@@ -0,0 +1,45 @@
# 即刻 (Jike)
**Mode**: 🔐 Browser · **Domain**: `web.okjike.com`
## Commands
| Command | Description |
|---------|-------------|
| `opencli jike feed` | 即刻首页动态流 |
| `opencli jike search` | 搜索即刻帖子 |
| `opencli jike post` | 帖子详情及评论 |
| `opencli jike topic` | 话题详情 |
| `opencli jike user` | 用户资料 |
| `opencli jike create` | 发布即刻动态 |
| `opencli jike comment` | 评论即刻帖子 |
| `opencli jike like` | 点赞即刻帖子 |
| `opencli jike repost` | 转发即刻帖子 |
| `opencli jike notifications` | 即刻通知 |
## Usage Examples
```bash
# View feed
opencli jike feed --limit 10
# Search posts
opencli jike search --query "AI" --limit 20
# View post details and comments
opencli jike post --id <post-id>
# Create a new post
opencli jike create --content "Hello Jike!"
# Like a post
opencli jike like --id <post-id>
# JSON output
opencli jike feed -f json
```
## Prerequisites
- Chrome running and **logged into** web.okjike.com
- [Browser Bridge extension](/guide/browser-bridge) installed
docs/adapters/browser/jimeng.md
+39
View File
@@ -0,0 +1,39 @@
# 即梦AI (Jimeng)
**Mode**: 🔐 Browser · **Domain**: `jimeng.jianying.com`
## Commands
| Command | Description |
|---------|-------------|
| `opencli jimeng generate` | 即梦AI 文生图 — 输入 prompt 生成图片 |
| `opencli jimeng history` | 查看生成历史 |
## Usage Examples
```bash
# Generate an image
opencli jimeng generate --prompt "一只在星空下的猫"
# Use a specific model
opencli jimeng generate --prompt "cyberpunk city" --model high_aes_general_v50
# Set custom wait timeout
opencli jimeng generate --prompt "sunset landscape" --wait 60
# View generation history
opencli jimeng history --limit 10
```
### Options (generate)
| Option | Description |
|--------|-------------|
| `--prompt` | Image description prompt (required) |
| `--model` | Model: `high_aes_general_v50` (5.0 Lite), `high_aes_general_v42` (4.6), `high_aes_general_v40` (4.0) |
| `--wait` | Wait seconds for generation (default: 40) |
## Prerequisites
- Chrome running and **logged into** jimeng.jianying.com
- [Browser Bridge extension](/guide/browser-bridge) installed
docs/adapters/browser/linux-do.md
+45
View File
@@ -0,0 +1,45 @@
# LINUX DO
**Mode**: 🔐 Browser · **Domain**: `linux.do`
## Commands
| Command | Description |
|---------|-------------|
| `opencli linux-do hot` | 热门话题 |
| `opencli linux-do latest` | 最新话题 |
| `opencli linux-do categories` | 板块列表 |
| `opencli linux-do category` | 板块话题 |
| `opencli linux-do search` | 搜索话题 |
| `opencli linux-do topic` | 话题详情 |
## Usage Examples
```bash
# Hot topics this week
opencli linux-do hot --limit 20
# Hot topics by period
opencli linux-do hot --period daily
opencli linux-do hot --period monthly
# Latest topics
opencli linux-do latest --limit 10
# List all categories
opencli linux-do categories
# Search topics
opencli linux-do search --query "NixOS"
# View topic details
opencli linux-do topic --id 12345
# JSON output
opencli linux-do hot -f json
```
## Prerequisites
- Chrome running and **logged into** linux.do
- [Browser Bridge extension](/guide/browser-bridge) installed
docs/adapters/browser/sinafinance.md
+35
View File
@@ -0,0 +1,35 @@
# 新浪财经 (Sina Finance)
**Mode**: 🌐 Public · **Domain**: `finance.sina.com.cn`
## Commands
| Command | Description |
|---------|-------------|
| `opencli sinafinance news` | 新浪财经 7×24 小时实时快讯 |
## Usage Examples
```bash
# Latest financial news
opencli sinafinance news --limit 20
# Filter by type
opencli sinafinance news --type 1 # A股
opencli sinafinance news --type 2 # 宏观
opencli sinafinance news --type 6 # 国际
# JSON output
opencli sinafinance news -f json
```
### Options
| Option | Description |
|--------|-------------|
| `--limit` | Max results, up to 50 (default: 20) |
| `--type` | News type: `0`=全部, `1`=A股, `2`=宏观, `3`=公司, `4`=数据, `5`=市场, `6`=国际, `7`=观点, `8`=央行, `9`=其它 |
## Prerequisites
- No browser required — uses public API
docs/adapters/browser/stackoverflow.md
+35
View File
@@ -0,0 +1,35 @@
# Stack Overflow
**Mode**: 🌐 Public · **Domain**: `stackoverflow.com`
## Commands
| Command | Description |
|---------|-------------|
| `opencli stackoverflow hot` | Hot questions |
| `opencli stackoverflow search` | Search questions |
| `opencli stackoverflow bounties` | Questions with active bounties |
| `opencli stackoverflow unanswered` | Unanswered questions |
## Usage Examples
```bash
# Hot questions
opencli stackoverflow hot --limit 10
# Search questions
opencli stackoverflow search --query "async await" --limit 20
# Active bounties
opencli stackoverflow bounties --limit 10
# Unanswered questions
opencli stackoverflow unanswered --limit 10
# JSON output
opencli stackoverflow hot -f json
```
## Prerequisites
- No browser required — uses public Stack Exchange API
docs/adapters/browser/weread.md
+48
View File
@@ -0,0 +1,48 @@
# 微信读书 (WeRead)
**Mode**: 🔐 Browser · **Domain**: `weread.qq.com`
## Commands
| Command | Description |
|---------|-------------|
| `opencli weread shelf` | List books on your bookshelf |
| `opencli weread search` | Search books on WeRead |
| `opencli weread book` | View book details |
| `opencli weread ranking` | Book rankings by category |
| `opencli weread notebooks` | List books that have highlights or notes |
| `opencli weread highlights` | List your highlights (underlines) in a book |
| `opencli weread notes` | List your notes (thoughts) on a book |
## Usage Examples
```bash
# View your bookshelf
opencli weread shelf --limit 20
# Search books
opencli weread search --query "三体"
# View book details
opencli weread book --id <book-id>
# Book rankings
opencli weread ranking --limit 10
# List books with notes/highlights
opencli weread notebooks
# View highlights for a book
opencli weread highlights --id <book-id>
# View your notes
opencli weread notes --id <book-id>
# JSON output
opencli weread shelf -f json
```
## Prerequisites
- Chrome running and **logged into** weread.qq.com
- [Browser Bridge extension](/guide/browser-bridge) installed
docs/adapters/browser/wikipedia.md
+30
View File
@@ -0,0 +1,30 @@
# Wikipedia
**Mode**: 🌐 Public · **Domain**: `wikipedia.org`
## Commands
| Command | Description |
|---------|-------------|
| `opencli wikipedia search` | Search Wikipedia articles |
| `opencli wikipedia summary` | Get Wikipedia article summary |
## Usage Examples
```bash
# Search articles
opencli wikipedia search --query "quantum computing" --limit 10
# Get article summary
opencli wikipedia summary --title "Artificial intelligence"
# Search in other languages
opencli wikipedia search --query "人工智能" --lang zh
# JSON output
opencli wikipedia search --query "Rust" -f json
```
## Prerequisites
- No browser required — uses public Wikipedia API
docs/adapters/index.md
+12
View File
@@ -21,6 +21,12 @@ Run `opencli list` for the live registry.
| **[ctrip](/adapters/browser/ctrip)** | `search` | 🔐 Browser |
| **[reuters](/adapters/browser/reuters)** | `search` | 🔐 Browser |
| **[smzdm](/adapters/browser/smzdm)** | `search` | 🔐 Browser |
| **[jike](/adapters/browser/jike)** | `feed` `search` `post` `topic` `user` `create` `comment` `like` `repost` `notifications` | 🔐 Browser |
| **[jimeng](/adapters/browser/jimeng)** | `generate` `history` | 🔐 Browser |
| **[linux-do](/adapters/browser/linux-do)** | `hot` `latest` `categories` `category` `search` `topic` | 🔐 Browser |
| **[chaoxing](/adapters/browser/chaoxing)** | `assignments` `exams` | 🔐 Browser |
| **[grok](/adapters/browser/grok)** | `ask` | 🔐 Browser |
| **[weread](/adapters/browser/weread)** | `shelf` `search` `book` `ranking` `notebooks` `highlights` `notes` | 🔐 Browser |
## Public API Adapters
@@ -32,6 +38,12 @@ Run `opencli list` for the live registry.
| **[apple-podcasts](/adapters/browser/apple-podcasts)** | `search` `episodes` `top` | 🌐 Public |
| **[xiaoyuzhou](/adapters/browser/xiaoyuzhou)** | `podcast` `podcast-episodes` `episode` | 🌐 Public |
| **[yahoo-finance](/adapters/browser/yahoo-finance)** | `quote` | 🌐 Public |
| **[arxiv](/adapters/browser/arxiv)** | `search` `paper` | 🌐 Public |
| **[barchart](/adapters/browser/barchart)** | `quote` `options` `greeks` `flow` | 🌐 Public |
| **[hf](/adapters/browser/hf)** | `top` | 🌐 Public |
| **[sinafinance](/adapters/browser/sinafinance)** | `news` | 🌐 Public |
| **[stackoverflow](/adapters/browser/stackoverflow)** | `hot` `search` `bounties` `unanswered` | 🌐 Public |
| **[wikipedia](/adapters/browser/wikipedia)** | `search` `summary` | 🌐 Public |
## Desktop Adapters
scripts/check-doc-coverage.sh
Executable
+69
View File
@@ -0,0 +1,69 @@
#!/usr/bin/env bash
# check-doc-coverage.sh — Verify every adapter in src/clis/ has a doc page.
#
# Exit codes:
# 0 — all adapters have docs
# 1 — at least one adapter is missing documentation
#
# Usage:
# bash scripts/check-doc-coverage.sh # report only
# bash scripts/check-doc-coverage.sh --strict # exit 1 on missing docs
set -euo pipefail
STRICT=false
if [[ "${1:-}" == "--strict" ]]; then
STRICT=true
fi
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
ROOT_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
SRC_DIR="$ROOT_DIR/src/clis"
DOCS_DIR="$ROOT_DIR/docs/adapters"
missing=()
covered=0
total=0
for adapter_dir in "$SRC_DIR"/*/; do
adapter_name="$(basename "$adapter_dir")"
total=$((total + 1))
# Check if doc exists in browser/ or desktop/ subdirectories
if [[ -f "$DOCS_DIR/browser/$adapter_name.md" ]] || \
[[ -f "$DOCS_DIR/desktop/$adapter_name.md" ]]; then
covered=$((covered + 1))
else
# Handle directory name mismatches (e.g., discord-app -> discord)
alt_name="${adapter_name%-app}"
if [[ "$alt_name" != "$adapter_name" ]] && \
{ [[ -f "$DOCS_DIR/browser/$alt_name.md" ]] || \
[[ -f "$DOCS_DIR/desktop/$alt_name.md" ]]; }; then
covered=$((covered + 1))
else
missing+=("$adapter_name")
fi
fi
done
echo "📊 Doc Coverage: $covered/$total adapters documented"
echo ""
if [[ ${#missing[@]} -gt 0 ]]; then
echo "⚠️ Missing docs for ${#missing[@]} adapter(s):"
for name in "${missing[@]}"; do
echo " - $name → create docs/adapters/browser/$name.md or docs/adapters/desktop/$name.md"
done
echo ""
if $STRICT; then
echo "❌ Doc check failed (--strict mode)."
exit 1
else
echo "💡 Run with --strict to fail CI on missing docs."
exit 0
fi
else
echo "✅ All adapters have documentation."
exit 0
fi