rdoc 6.17.0 → 8.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2bb82d9eff1cf5ae3ee5276c97b12d57694d28c64a70ee9f318d4468c904999e
-  data.tar.gz: f7073f27e9b4a15e3b7792f777bb8b2bc991bde74409e15cdb5bd7be1900f2db
+  metadata.gz: 8bd46d161ae9d2249a6e2ea1afdb46e08cdc737260427c472fe39981d6ea6d00
+  data.tar.gz: 81e455d982e6e564e84058ba420aa59ee9d7792f93de961051d705bada6cd4f0
 SHA512:
-  metadata.gz: 76a11b7a7529c4b008488ba22f4aa0c8c5dd2cbfff19ec795f0fa5f16e0d7c7f4913d69c2cc11d18653f8d0a4bde559f2b2a893b9dba9d8aec34faaec557b935
-  data.tar.gz: 5af47e79dc6fde12b8aa9809a0eb845db18031a907140484ea95ef16399a592c879445b8f725ae4eabfbfe5d3250656926698fa2a35b3426605420ca9961579f
+  metadata.gz: 3a9fb465374b2b6fa07e949c50284394377b48657de07da3a78604f2b646558a4ebe4dc06aaea4e773f185370256971c5563159ab1c0dab6bd5b65cc3e2a94f3
+  data.tar.gz: 99b8a3b9ac9b568a4ab8a23fa3cd5dd6b1385f562d800a54094d533bf153b3696337d217df999f94c88236049a357f3fa655b592cba7106f50829e9d72f4d02f

data/CONTRIBUTING.md

@@ -0,0 +1,193 @@
+# Contributing to RDoc
+
+Thank you for your interest in contributing to RDoc! This document provides guidelines and instructions for contributing.
+
+## Reporting Bugs
+
+If you think you found a bug, open an issue on the [issue tracker](https://github.com/ruby/rdoc/issues) on GitHub.
+
+When reporting a bug:
+
+- Include a sample file that illustrates the problem, or link to the repository/gem associated with the bug
+- Include steps to reproduce the issue
+
+## Development Setup
+
+RDoc uses Bundler for development. To get started:
+
+```bash
+bundle install
+bundle exec rake
+```
+
+This will install dependencies and run the tests.
+
+If you're working on CSS or templates, you'll also want Node dependencies for the CSS linter:
+
+```bash
+npm install
+```
+
+If tests don't pass on the first run, check the [GitHub Actions page](https://github.com/ruby/rdoc/actions) to see if there are any known failures.
+
+**Note:** Generated parser files are committed to the repository. If you delete them (for example via `bundle exec rake clean`) or you change any `.ry`/`.kpeg` parser sources, run `bundle exec rake generate` before running tests.
+
+## Running Tests
+
+```bash
+# Run all tests (default task)
+bundle exec rake
+
+# Run unit tests only (excludes RubyGems integration)
+bundle exec rake normal_test
+
+# Run RubyGems integration tests only
+bundle exec rake rubygems_test
+
+# Verify generated parser files are current (CI check)
+bundle exec rake verify_generated
+```
+
+- **Test Framework:** [`test-unit`](https://github.com/test-unit/test-unit)
+- **Test Location:** `test/` directory
+- **Test Helper:** `test/lib/helper.rb`
+
+## Linting
+
+### RuboCop (Ruby Code)
+
+```bash
+# Check Ruby code style
+bundle exec rubocop
+
+# Auto-fix style issues
+bundle exec rubocop -A
+```
+
+### Herb Linter (ERB/RHTML Templates)
+
+```bash
+# Lint ERB template files
+npx @herb-tools/linter "**/*.rhtml"
+
+# Lint specific directory
+npx @herb-tools/linter "lib/**/*.rhtml"
+```
+
+**Template Location:** `lib/rdoc/generator/template/**/*.rhtml`
+
+### Stylelint (CSS Files)
+
+```bash
+# Lint CSS files
+npm run lint:css
+
+# Auto-fix style issues
+npm run lint:css -- --fix
+```
+
+## Type annotations
+
+RDoc is currently not a typed codebase. Despite not running a type checker, contributors have been
+adding some comment annotations to make the codebase easier to navigate and understand.
+
+These annotations use [Sorbet flavored RBS](https://sorbet.org/docs/rbs-support) annotations,
+so that we can tag definitions as abstract and override. For more information on RBS syntax,
+see the [documentation](https://github.com/ruby/rbs/blob/master/docs/syntax.md).
+
+## Parser Generation
+
+RDoc uses generated parsers for Markdown and RD formats.
+
+```bash
+# Generate all parser files from sources
+bundle exec rake generate
+
+# Remove generated parser files
+bundle exec rake clean
+
+# Verify generated files are in sync with sources (CI check)
+bundle exec rake verify_generated
+```
+
+**Source Files** (edit these):
+
+- `lib/rdoc/rd/block_parser.ry` → generates `block_parser.rb` via racc
+- `lib/rdoc/rd/inline_parser.ry` → generates `inline_parser.rb` via racc
+- `lib/rdoc/markdown.kpeg` → generates `markdown.rb` via kpeg
+
+**Important:**
+
+- Generated parser files **should be committed** to the repository
+- Do not edit generated `.rb` parser files directly
+- After modifying `.ry` or `.kpeg` source files, run `bundle exec rake generate`
+- CI runs `rake verify_generated` to ensure generated files are in sync with their sources
+
+## Documentation Generation
+
+```bash
+# Generate documentation (creates _site directory)
+bundle exec rake rdoc
+
+# Force regenerate documentation
+bundle exec rake rerdoc
+
+# Show documentation coverage
+bundle exec rake rdoc:coverage
+bundle exec rake coverage
+```
+
+- **Output Directory:** `_site/` (GitHub Pages compatible)
+- **Configuration:** `.rdoc_options` and `.document`
+
+## Themes
+
+RDoc ships with two HTML themes:
+
+- **Aliki** (default) - Modern theme with improved styling and navigation
+- **Darkfish** (deprecated) - Classic theme, will be removed in v9.0
+
+New feature development should focus on the Aliki theme. Darkfish will continue to receive bug fixes but no new features.
+
+Theme templates are located at `lib/rdoc/generator/template/<theme>/`.
+
+## Project Structure
+
+```
+lib/rdoc/
+├── rdoc.rb                    # Main entry point (RDoc::RDoc class)
+├── version.rb                 # Version constant
+├── task.rb                    # Rake task integration
+├── parser/                    # Source code parsers
+│   ├── ruby.rb                # Prism-based Ruby parser
+│   ├── c.rb                   # C extension parser
+│   └── ...
+├── generator/                 # Documentation generators
+│   ├── aliki.rb               # HTML generator (default theme)
+│   ├── darkfish.rb            # HTML generator (deprecated, will be removed in v9.0)
+│   ├── markup.rb              # Markup format generator
+│   ├── ri.rb                  # RI command generator
+│   └── template/              # ERB templates
+│       ├── aliki/             # Aliki theme (default)
+│       └── darkfish/          # Darkfish theme (deprecated)
+├── markup/                    # Markup parsing and formatting
+├── code_object/               # AST objects for documented items
+├── markdown.kpeg              # Parser source (edit this)
+├── markdown.rb                # Generated parser (do not edit)
+├── markdown/                  # Markdown parsing
+│   └── byte_runtime.rb        # Byte-offset parser runtime
+├── rd/                        # RD format parsing
+│   ├── block_parser.ry        # Parser source (edit this)
+│   ├── block_parser.rb        # Generated parser (do not edit)
+│   ├── inline_parser.ry       # Parser source (edit this)
+│   └── inline_parser.rb       # Generated parser (do not edit)
+└── ri/                        # RI (Ruby Info) tool
+
+test/                          # Test files
+├── lib/helper.rb              # Test helpers
+└── rdoc/                      # Main test directory
+```
+
+## Code of Conduct
+
+Please be respectful and constructive in all interactions. We're all here to make RDoc better!

data/LEGAL.rdoc

@@ -4,6 +4,12 @@
 
 The files in this distribution are covered by the Ruby license (see LICENSE) except the features mentioned below:
 
+Aliki::
+  Aliki was written by Stan Lo and is included under the MIT license.
+
+  * lib/rdoc/generator/aliki.rb
+  * lib/rdoc/generator/template/aliki/*
+
 Darkfish::
   Darkfish was written by Michael Granger and is included under the BSD 3-Clause
   license.  Darkfish contains images from the Silk Icons set by Mark James.

data/LICENSE.rdoc

@@ -1,3 +1,7 @@
+:stopdoc:
+SPDX-License-Identifier: Ruby or GPL-2.0-only
+:startdoc:
+
 = License
 
 RDoc is copyrighted free software.

data/README.md

@@ -3,6 +3,10 @@
 - GitHub: [https://github.com/ruby/rdoc](https://github.com/ruby/rdoc)
 - Issues: [https://github.com/ruby/rdoc/issues](https://github.com/ruby/rdoc/issues)
 
+<p align="center" class="rdoc-logo">
+  <img src="rdoc-logo.svg" alt="RDoc" width="168" height="198">
+</p>
+
 ## Description
 
 RDoc produces HTML and command-line documentation for Ruby projects.  RDoc includes the `rdoc` and `ri` tools for generating and displaying documentation from the command-line.
@@ -37,7 +41,9 @@ rdoc --main README.md
 
 You'll find information on the various formatting tricks you can use in comment blocks in the documentation this generates.
 
-RDoc uses file extensions to determine how to process each file.  File names ending `.rb` and `.rbw` are assumed to be Ruby source.  Files ending `.c` are parsed as C files.  All other files are assumed to contain just Markup-style markup (with or without leading `#` comment markers).  If directory names are passed to RDoc, they are scanned recursively for C and Ruby source files only.
+RDoc uses file extensions to determine how to process each file.  File names ending `.rb` and `.rbw` are assumed to be Ruby source.  Files ending `.c` are parsed as C files.  Files ending `.rbs` are parsed as RBS signature files.  All other files are assumed to contain just Markup-style markup (with or without leading `#` comment markers).  If directory names are passed to RDoc, they are scanned recursively for C, Ruby, and RBS source files.
+
+RBS files can document classes, modules, methods, attributes, and constants.  When RBS declarations match objects already documented from Ruby source, their comments and type signatures extend the existing documentation.
 
 To generate documentation using `rake` see [RDoc::Task](https://ruby.github.io/rdoc/RDoc/Task.html).
 
@@ -48,7 +54,7 @@ require 'rdoc/rdoc'
 
 options = RDoc::Options.new
 options.files = ['a.rb', 'b.rb']
-options.setup_generator 'darkfish'
+options.setup_generator 'aliki'
 # see RDoc::Options
 
 rdoc = RDoc::RDoc.new
@@ -60,7 +66,7 @@ You can specify the target files for document generation with `.document` file i
 
 ## Writing Documentation
 
-To write documentation for RDoc place a comment above the class, module, method, constant, or attribute you want documented:
+To write documentation for RDoc, place a comment above the class, module, method, constant, or attribute you want documented:
 
 ```rb
 ##
@@ -80,26 +86,144 @@ class Shape
 end
 ```
 
-The default comment markup format is the RDoc::Markup format. TomDoc, Markdown and RD format comments are also supported.  You can set the default comment format for your entire project by creating a `.rdoc_options` file.  See RDoc::Options@Saved+Options for instructions on creating one.  You can also set the comment format for a single file through the `:markup:` directive, but this is only recommended if you wish to switch markup formats.  See RDoc::Markup@Other+directives.
+### Markup Formats
+
+RDoc supports multiple markup formats:
+
+| Format | File Extensions | Default For |
+|--------|-----------------|-------------|
+| [RDoc](doc/markup_reference/rdoc.rdoc) | `.rdoc` | `.rb`, `.c` files |
+| [Markdown](doc/markup_reference/markdown.md) | `.md` | None |
+| RD | `.rd` | None |
+| TomDoc | N/A | None |
+
+**RDoc markup** is currently the default format for Ruby and C files. However, we plan to retire it in favor of Markdown in the future.
+
+**Markdown** support is actively being improved. Once it reaches feature parity with RDoc markup, it will become the default format.
+
+For standalone documentation files, we recommend writing `.md` files instead of `.rdoc` files.
+
+**RD** and **TomDoc** are legacy formats. We highly discourage their use in new projects.
+
+### Specifying Markup Format
+
+**Per-file:** Add a `:markup:` directive at the top of a Ruby file:
+
+```ruby
+# :markup: markdown
+
+# This class uses **Markdown** for documentation.
+class MyClass
+end
+```
 
-Comments can contain directives that tell RDoc information that it cannot otherwise discover through parsing.  See RDoc::Markup@Directives to control what is or is not documented, to define method arguments or to break up methods in a class by topic.  See RDoc::Parser::Ruby for directives used to teach RDoc about metaprogrammed methods.
+**Per-project:** Create a `.rdoc_options` file in your project root:
+
+```yaml
+markup: markdown
+```
+
+**Command line:**
+
+```bash
+rdoc --markup markdown
+```
+
+### Feature Differences
+
+| Feature | RDoc Markup | Markdown |
+|---------|-------------|----------|
+| Headings | `= Heading` | `# Heading` |
+| Bold | `*word*` | `**word**` |
+| Italic | `_word_` | `*word*` |
+| Monospace | `+word+` | `` `word` `` |
+| Links | `{text}[url]` | `[text](url)` |
+| Code blocks | Indent 2 spaces | Fenced with ``` |
+| Cross-references | Automatic | Automatic |
+| Directives (`:nodoc:`, etc.) | Supported | Supported |
+| Tables | Not supported | Supported |
+| Strikethrough | `<del>text</del>` | `~~text~~` |
+| Footnotes | Not supported | Supported |
+
+For complete syntax documentation, see:
+
+- [RDoc Markup Reference](doc/markup_reference/rdoc.rdoc)
+- [Markdown Reference](doc/markup_reference/markdown.md)
+
+### Directives
+
+Comments can contain directives that tell RDoc information that it cannot otherwise discover through parsing. See RDoc::Markup@Directives to control what is or is not documented, to define method arguments or to break up methods in a class by topic. See RDoc::Parser::Ruby for directives used to teach RDoc about metaprogrammed methods.
 
 See RDoc::Parser::C for documenting C extensions with RDoc.
 
-To determine how well your project is documented run `rdoc -C lib` to get a documentation coverage report.  `rdoc -C1 lib` includes parameter names in the documentation coverage report.
+### Documentation Coverage
+
+To determine how well your project is documented run `rdoc -C lib` to get a documentation coverage report. `rdoc -C1 lib` includes parameter names in the documentation coverage report.
 
 ## Theme Options
 
-There are a few community-maintained themes for RDoc:
+RDoc ships with two built-in themes:
+
+- **Aliki** (default) - A modern, clean theme with improved navigation and search
+- **Darkfish** (deprecated) - The classic theme, will be removed in v9.0
+
+To use the Darkfish theme instead of the default Aliki theme:
+
+```shell
+rdoc --format darkfish
+```
+
+Or in your `.rdoc_options` file:
+
+```yaml
+generator_name: darkfish
+```
+
+There are also a few community-maintained themes for RDoc:
 
 - [rorvswild-theme-rdoc](https://github.com/BaseSecrete/rorvswild-theme-rdoc)
 - [hanna](https://github.com/jeremyevans/hanna) (a fork maintained by [Jeremy Evans](https://github.com/jeremyevans))
 
 Please follow the theme's README for usage instructions.
 
+## Live Preview Server
+
+RDoc includes a built-in server for previewing documentation while you edit source files. It parses your code once on startup, then watches for changes and auto-refreshes the browser.
+
+```shell
+rdoc --server
+```
+
+This starts a server at `http://localhost:4000`. You can specify a different port:
+
+```shell
+rdoc --server=8080
+```
+
+Or use the Rake task:
+
+```shell
+rake rdoc:server
+```
+
+### How It Works
+
+- Parses all source files on startup and serves pages from memory using the Aliki theme
+- A background thread polls file mtimes every second
+- When a file changes, only that file is re-parsed — the browser refreshes automatically
+- New files are detected and added; deleted files are removed
+
+**No external dependencies.** The server uses Ruby's built-in `TCPServer` (`socket` stdlib) — no WEBrick or other gems required.
+
+### Limitations
+
+- **Reopened classes and file deletion.** If a class is defined across multiple files (e.g. `Foo` in both `a.rb` and `b.rb`), deleting one file removes the entire class from the store, including parts from the other file. Saving the remaining file triggers a re-parse that restores it.
+- **Full cache invalidation.** Any file change clears all cached pages. This is simple and correct — rendering is fast (~ms per page), parsing is the expensive part and is done incrementally.
+- **No HTTPS or HTTP/2.** The server is intended for local development preview only.
+
 ## Bugs
 
-See CONTRIBUTING.rdoc for information on filing a bug report.  It's OK to file a bug report for anything you're having a problem with.  If you can't figure out how to make RDoc produce the output you like that is probably a documentation bug.
+See [CONTRIBUTING.md](CONTRIBUTING.md) for information on filing a bug report.  It's OK to file a bug report for anything you're having a problem with.  If you can't figure out how to make RDoc produce the output you like that is probably a documentation bug.
 
 ## License