rdoc 6.15.1 → 7.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ed79e2cda1c5cd7113829e3fcfbbece5c1d5332e9046778c2581d28059afd9e7
-  data.tar.gz: cc77a3249231ee94df7d06090d9a683e0c7f71f5924186e2f0dcae5b01ec5b74
+  metadata.gz: c14913bad669603f9b9662966297c2e33b45af4500c9cd71bbff067da334ee1a
+  data.tar.gz: 4e40f1f5b579891945cc7e365bf3977863eb9236eb9af872d870cb46317d191b
 SHA512:
-  metadata.gz: 43bd516f9ffb4f33e76c6186c8b0429525d4729172a25de895a2f1d69f7c523bdc8868c42dc55dc17863f6daa927a56d1aaefbb9edc5519a4885f2a5b60e0cbf
-  data.tar.gz: 368780ba1a40869aa6a26e2a5734d13bb5ec25e4d47dcea78cb0de2c117bad7b8e964ea69b857aadc799f492f72d51a7d68a7259f357c2d23c9a13064c33ce3b
+  metadata.gz: 3aadc0477ea9dd400c1128c512352745b7835171f998c89a83a2827190a41e171d6fa5b89e5c9a27da0bab76fa5492236f7ce13d59ce64970cd414abd9da806c
+  data.tar.gz: a6949c4950b1fd69c8176330e1c6bedb4912281521f31f66d36b123e912d7fe2bf4736cfd0dae22ac8de939badd817bbd771f500bbc65f8041ab7939d43a3e14

data/CONTRIBUTING.md

@@ -0,0 +1,196 @@
+# 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
+- `lib/rdoc/markdown/literals.kpeg` → generates `literals.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 v8.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                # Ruby code parser
+│   ├── c.rb                   # C extension parser
+│   ├── prism_ruby.rb          # Prism-based Ruby parser
+│   └── ...
+├── generator/                 # Documentation generators
+│   ├── aliki.rb               # HTML generator (default theme)
+│   ├── darkfish.rb            # HTML generator (deprecated, will be removed in v8.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
+│   ├── literals.kpeg          # Parser source (edit this)
+│   └── literals.rb            # Generated parser (do not edit)
+├── 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/History.rdoc

@@ -163,7 +163,7 @@
   * Moved old DEVELOPERS file to CONTRIBUTING to match github conventions.
   * TomDoc output now has a "Returns" heading.  Issue #234 by Brian Henderson
   * Metaprogrammed methods can now use the :args: directive in addition to the
-    :call-seq: directive.  Issue #236 by Mike Moore.
+    \:call-seq: directive.  Issue #236 by Mike Moore.
   * Sections can be linked to using "@" like labels.  If a section and a label
     have the same name the section will be preferred.  Issue #233 by Brian
     Henderson.

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/README.md

@@ -48,7 +48,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 +60,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,17 +80,100 @@ 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
 
-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.
+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
+```
+
+**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 v8.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))
@@ -99,7 +182,7 @@ Please follow the theme's README for usage instructions.
 
 ## 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