Skip to content

Commit f234e00

Browse files
st0012st0012
committed
Add AGENTS.md and CLAUDE.md to the project
1 parent c03a250 commit f234e00

File tree

2 files changed

+236
-0
lines changed

2 files changed

+236
-0
lines changed

‎AGENTS.md‎

Lines changed: 224 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,224 @@
1+
# RDoc Project Guide for AI Agents
2+
3+
## Project Overview
4+
5+
**RDoc** is Ruby's default documentation generation tool that produces HTML and command-line documentation for Ruby projects. It parses Ruby source code, C extensions, and markup files to generate documentation.
6+
7+
- **Repository:** https://github.com/ruby/rdoc
8+
- **Homepage:** https://ruby.github.io/rdoc
9+
- **Required Ruby:** >= 2.6.0 (targets 3.0+)
10+
- **Main Executables:** `rdoc` and `ri`
11+
12+
## Key Development Commands
13+
14+
### Testing
15+
16+
```bash
17+
# Run all tests (default task)
18+
bundle exec rake
19+
20+
# Run unit tests only (excludes RubyGems integration)
21+
bundle exec rake normal_test
22+
23+
# Run RubyGems integration tests only
24+
bundle exec rake rubygems_test
25+
26+
# Verify generated parser files are current (CI check)
27+
bundle exec rake verify_generated
28+
```
29+
30+
**Test Framework:** Test::Unit with `test-unit` gem
31+
**Test Location:** `test/` directory
32+
**Test Helper:** `test/lib/helper.rb`
33+
34+
### Linting
35+
36+
#### RuboCop (Ruby Linting)
37+
38+
```bash
39+
# Check Ruby code style
40+
bundle exec rubocop
41+
42+
# Auto-fix style issues
43+
bundle exec rubocop -A
44+
```
45+
46+
**Configuration:** `.rubocop.yml`
47+
48+
- Target Ruby: 3.0
49+
- Minimal cop set (opt-in approach)
50+
- Excludes generated parser files
51+
52+
#### Herb Linter (ERB/RHTML Files)
53+
54+
```bash
55+
# Lint ERB template files
56+
npx @herb-tools/linter "**/*.rhtml"
57+
58+
# Lint specific directory
59+
npx @herb-tools/linter "lib/**/*.rhtml"
60+
```
61+
62+
**Template Location:** `lib/rdoc/generator/template/**/*.rhtml`
63+
**CI Workflow:** `.github/workflows/lint.yml`
64+
**VS Code Extension:** `marcoroth.herb-lsp` (recommended in `.vscode/extensions.json`)
65+
66+
### Documentation Generation
67+
68+
```bash
69+
# Generate documentation (creates _site directory)
70+
bundle exec rake rdoc
71+
72+
# Force regenerate documentation
73+
bundle exec rake rerdoc
74+
75+
# Show documentation coverage
76+
bundle exec rake rdoc:coverage
77+
bundle exec rake coverage
78+
```
79+
80+
**Output Directory:** `_site/` (GitHub Pages compatible)
81+
**Configuration:** `.rdoc_options`
82+
83+
### Parser Generation
84+
85+
RDoc uses generated parsers for Markdown and RD formats:
86+
87+
```bash
88+
# Generate all parser files from sources
89+
bundle exec rake generate
90+
91+
# Remove generated parser files
92+
bundle exec rake clean
93+
```
94+
95+
**Generated Files:**
96+
97+
- `lib/rdoc/rd/block_parser.rb` (from `.ry` via racc)
98+
- `lib/rdoc/rd/inline_parser.rb` (from `.ry` via racc)
99+
- `lib/rdoc/markdown.rb` (from `.kpeg` via kpeg)
100+
- `lib/rdoc/markdown/literals.rb` (from `.kpeg` via kpeg)
101+
102+
**Note:** These files are auto-generated and should not be edited manually. Always regenerate after modifying source `.ry` or `.kpeg` files.
103+
104+
### Building and Releasing
105+
106+
```bash
107+
# Build gem package
108+
bundle exec rake build
109+
110+
# Install gem locally
111+
bundle exec rake install
112+
113+
# Create tag and push to rubygems.org
114+
bundle exec rake release
115+
```
116+
117+
## Project Structure
118+
119+
```sh
120+
lib/rdoc/
121+
├── rdoc.rb # Main entry point (RDoc::RDoc class)
122+
├── version.rb # Version constant
123+
├── task.rb # Rake task integration
124+
├── parser/ # Source code parsers (Ruby, C, Markdown, RD)
125+
│ ├── ruby.rb # Ruby code parser
126+
│ ├── c.rb # C extension parser
127+
│ ├── prism_ruby.rb # Prism-based Ruby parser
128+
│ └── ...
129+
├── generator/ # Documentation generators
130+
│ ├── darkfish.rb # HTML generator (default theme)
131+
│ ├── markup.rb # Markup format generator
132+
│ ├── ri.rb # RI command generator
133+
│ └── template/darkfish/ # ERB templates (.rhtml files)
134+
├── markup/ # Markup parsing and formatting
135+
├── code_object/ # AST objects for documented items
136+
├── markdown/ # Markdown parsing
137+
├── rd/ # RD format parsing
138+
└── ri/ # RI (Ruby Info) tool
139+
140+
test/ # 79 test files
141+
├── lib/helper.rb # Test helpers
142+
└── rdoc/ # Main test directory
143+
144+
exe/
145+
├── rdoc # rdoc command executable
146+
└── ri # ri command executable
147+
```
148+
149+
## Important Files
150+
151+
### Configuration
152+
153+
- `.rubocop.yml` - RuboCop configuration (main)
154+
- `.generated_files_rubocop.yml` - RuboCop config for generated files
155+
- `.rdoc_options` - RDoc generation options
156+
- `.document` - File list for documentation
157+
- `Rakefile` - Task definitions
158+
- `lib/rdoc/task.rb` - Task definitions provided by RDoc
159+
- `rdoc.gemspec` - Gem specification
160+
- `Gemfile` - Development dependencies
161+
162+
### CI/CD
163+
164+
- `.github/workflows/test.yml` - Test execution across Ruby versions/platforms
165+
- `.github/workflows/lint.yml` - Linting (RuboCop + Herb)
166+
- `.github/workflows/push_gem.yml` - Gem publishing
167+
168+
### Documentation
169+
170+
- `README.md` - Basic usage guide
171+
- `ExampleRDoc.rdoc` - RDoc markup examples
172+
- `doc/rdoc/markup_reference.rb` - RDoc markup references
173+
- `ExampleMarkdown.md` - Markdown examples
174+
175+
## Architecture Notes
176+
177+
### Pluggable System
178+
179+
- **Parsers:** Ruby, C, Markdown, RD, Prism-based Ruby (experimental)
180+
- **Generators:** HTML/Darkfish, RI, POT (gettext), JSON, Markup
181+
182+
## Common Workflows
183+
184+
Do NOT commit anything. Ask the developer to review the changes after tasks are finished.
185+
186+
NEVER pushes code to any repositories.
187+
188+
### Making Code Changes
189+
190+
Use Red, Green, Refactor approach:
191+
192+
1. **Ensure Ruby version**: Verify you're using Ruby 3.3.0+ (prepend `chruby <ruby version>` if needed)
193+
2. **Red - Write failing tests**: Add tests that fail for the new behavior
194+
3. **Verify failure**: Run `bundle exec rake` to confirm tests fail as expected
195+
4. **Green - Make it work**: Implement the minimum code to make tests pass
196+
5. **Refactor - Make it right**: Improve code quality while keeping tests green
197+
- Run `bundle exec rake` after each refactor to ensure tests still pass
198+
- Iterate on steps 4-5 as needed
199+
6. **Lint your changes**:
200+
- Ruby code: `bundle exec rubocop -A` (auto-fix when possible)
201+
- ERB templates: `npx @herb-tools/linter "**/*.rhtml"` (if modified)
202+
203+
### Modifying Parsers
204+
205+
1. Edit source files (`.ry` or `.kpeg`)
206+
2. Regenerate: `bundle exec rake generate`
207+
3. Verify: `bundle exec rake verify_generated`
208+
4. Run tests: `bundle exec rake`
209+
210+
### Updating Documentation
211+
212+
1. Modify documentation comments in source
213+
2. Regenerate: `bundle exec rake rerdoc`
214+
3. Check output in `_site/` directory
215+
4. Check coverage: `bundle exec rake coverage`
216+
217+
## Notes for AI Agents
218+
219+
1. **Always run tests** after making changes: `bundle exec rake`
220+
2. **Check both RuboCop and Herb** for linting
221+
3. **Regenerate parsers** if you modify `.ry` or `.kpeg` files
222+
4. **Use `rake rerdoc`** to regenerate documentation (not just `rdoc`)
223+
5. **Verify generated files** with `rake verify_generated`
224+
6. **Don't edit generated files** directly (in `lib/rdoc/markdown/` and `lib/rdoc/rd/`)

‎CLAUDE.md‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
# Claude Code Instructions for RDoc
2+
3+
Please refer to `AGENTS.md` for comprehensive project documentation, including:
4+
5+
- Rake tasks and workflows
6+
- Testing setup
7+
- Linting configuration
8+
- Project structure
9+
- Development commands
10+
- CI/CD information
11+
12+
All project-specific instructions and guidelines are maintained in `AGENTS.md`.

0 commit comments

Comments
 (0)