Commit bc31f193 authored by Jan Reimes's avatar Jan Reimes
Browse files

docs(quick-reference): enhance CLI command documentation

- Added "When to Use" sections for various commands
- Documented command categories and short aliases
- Improved comparison tables for `crawl-tdocs` vs `crawl-meetings`
  and `query-tdocs` vs `query-meetings`
- Restructured document organization for better clarity
parent 05e31220
Loading
Loading
Loading
Loading
+17 −8
Original line number Diff line number Diff line
@@ -107,6 +107,7 @@ tdoc-crawler crawl-tdocs [OPTIONS]
Crawl TDoc metadata from the 3GPP FTP server. TDocs are fetched based on the meetings stored in the database ( populated by `crawl-meetings`).

**When to Use:**

- Initial TDoc metadata population
- Incremental updates to your local TDoc database
- After running `crawl-meetings` to refresh TDoc data
@@ -170,6 +171,7 @@ tdoc-crawler crawl-meetings [OPTIONS]
Crawl meeting metadata from the 3GPP portal. This command is required before crawling TDocs, as it populates the meetings database that `crawl-tdocs` uses to determine which meetings to crawl.

**When to Use:**

- Initial setup (required before first TDoc crawl)
- Periodic updates to meeting schedules
- Adding new working groups to crawl
@@ -226,6 +228,7 @@ tdoc-crawler query-tdocs [TDoc IDs] [OPTIONS]
Query TDoc metadata from the local database. If specific TDoc IDs are requested but not found, automatically triggers a targeted crawl to fetch missing data.

**When to Use:**

- Search for specific TDocs by ID
- Filter TDocs by working group, date range
- Export TDoc metadata as JSON or YAML
@@ -255,11 +258,12 @@ Query TDoc metadata from the local database. If specific TDoc IDs are requested
**Automatic Fetch Behavior:**

When you specify TDoc IDs that don't exist in your database, `query-tdocs` automatically:

1. Infers working groups from TDoc ID prefixes (`R*`→RAN, `S*`→SA, `T*`→CT, `C*`→CT)
2. Crawls the 3GPP portal to find meeting information for those TDocs
3. Crawls the FTP server to fetch TDoc metadata
4. Upserts the newly discovered data
5. Returns the complete results
1. Crawls the 3GPP portal to find meeting information for those TDocs
1. Crawls the FTP server to fetch TDoc metadata
1. Upserts the newly discovered data
1. Returns the complete results

This means you can often get away with just `tdoc-crawler query-tdocs R1-2400001` without manually running `crawl-meetings` and `crawl-tdocs` first.

@@ -300,6 +304,7 @@ tdoc-crawler query-meetings [OPTIONS]
Query meeting metadata from the local database. Unlike `query-tdocs`, this command only searches already-crawled meetings and does not trigger automatic fetching.

**When to Use:**

- Browse meeting schedules
- Find meetings by date range
- List meetings for specific working groups
@@ -370,15 +375,17 @@ tdoc-crawler open <TDoc ID> [--cache-dir PATH]
Download (if needed), extract, and open a TDoc file with the system default application.

**When to Use:**

- Quickly view a specific TDoc document
- Access TDoc attachments
- Open meeting materials directly from CLI

**Behavior:**

1. Queries the database; if missing, runs targeted crawl workflow
2. Downloads the TDoc into `<cache-dir>/tdocs/`
3. Extracts `.zip` payloads into `<cache-dir>/tdocs/<TDoc ID>/`
4. Opens the first file with the default system application
1. Downloads the TDoc into `<cache-dir>/tdocs/`
1. Extracts `.zip` payloads into `<cache-dir>/tdocs/<TDoc ID>/`
1. Opens the first file with the default system application

**Examples:**

@@ -399,6 +406,7 @@ tdoc-crawler checkout <TDoc IDs...> [--cache-dir PATH] [--force]
Download and extract TDoc(s) to a checkout folder (`<cache-dir>/checkout/`) for offline access.

**When to Use:**

- Batch download TDocs for offline review
- Extract meeting materials to a shared location
- Prepare TDoc collections for distribution
@@ -425,6 +433,7 @@ tdoc-crawler stats [--cache-dir PATH]
Display high-level database statistics including TDoc counts per working group, date ranges, and document type distribution.

**When to Use:**

- Check database population status
- Verify crawl results
- Get overview of stored data
+18 −8
Original line number Diff line number Diff line
@@ -12,45 +12,53 @@ Updated `docs/QUICK_REFERENCE.md` with comprehensive documentation for all CLI c
### Documentation Enhancements

1. **Added Command Overview Section**

   - Introduced command categories (Crawling, Querying, Utilities)
   - Documented short aliases (`ct`, `cm`, `qt`, `qm`)
   - Added typical workflow guide (Initial Setup → Incremental Updates → Querying)

2. **Added Command Differences Section**
1. **Added Command Differences Section**

   - Created comparison table for `crawl-tdocs` vs `crawl-meetings`
   - Created comparison table for `query-tdocs` vs `query-meetings`
   - Explained execution order requirements
   - Documented data sources and credential requirements

3. **Enhanced `crawl-tdocs` Documentation**
1. **Enhanced `crawl-tdocs` Documentation**

   - Added "When to Use" section
   - Comprehensive options table with descriptions
   - Expanded examples with more use cases
   - Documented parallel worker configuration

4. **Enhanced `crawl-meetings` Documentation**
1. **Enhanced `crawl-meetings` Documentation**

   - Added "When to Use" section
   - Comprehensive options table with descriptions
   - Documented ETSI Online credential usage
   - Added subgroup crawling examples

5. **Enhanced `query-tdocs` Documentation**
1. **Enhanced `query-tdocs` Documentation**

   - Added "When to Use" section
   - Documented automatic fetch behavior (targeted crawl)
   - Explained TDoc ID auto-inference from prefixes
   - Comprehensive options table

6. **Enhanced `query-meetings` Documentation**
1. **Enhanced `query-meetings` Documentation**

   - Added "When to Use" section
   - Clarified no automatic fetch (vs query-tdocs)
   - Documented subgroup aliases table
   - Comprehensive options table

7. **Enhanced Utility Commands Documentation**
1. **Enhanced Utility Commands Documentation**

   - Added "When to Use" sections for `open`, `checkout`, `stats`
   - Documented behavior details for `open` command

8. **Restructured Document Organization**
1. **Restructured Document Organization**

   - Command Overview first (workflow, aliases, categories)
   - Detailed command documentation with comparison tables
   - Utility commands section
@@ -69,12 +77,14 @@ Updated `docs/QUICK_REFERENCE.md` with comprehensive documentation for all CLI c
### Key Differences Documented

**`crawl-tdocs` vs `crawl-meetings`:**

- Data source (FTP vs Portal)
- Prerequisites (meetings DB required vs none)
- Execution order (after vs before)
- Credentials (none vs optional)

**`query-tdocs` vs `query-meetings`:**

- Returns (TDoc documents vs meeting schedules)
- Targeted fetch (automatic vs none)
- TDoc ID argument support (yes vs no)