diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000000..97eede6632 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,186 @@ +# 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 +``` + +## 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** - Modern theme with improved styling and navigation (will become the default) +- **Darkfish** - Classic theme (entering maintenance mode) + +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//`. + +## 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 +│ ├── darkfish.rb # HTML generator (default theme) +│ ├── markup.rb # Markup format generator +│ ├── ri.rb # RI command generator +│ └── template/ # ERB templates +│ ├── darkfish/ # Darkfish theme (maintenance mode) +│ └── aliki/ # Aliki theme (active development) +├── 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! diff --git a/CONTRIBUTING.rdoc b/CONTRIBUTING.rdoc deleted file mode 100644 index d76eb6b0ad..0000000000 --- a/CONTRIBUTING.rdoc +++ /dev/null @@ -1,219 +0,0 @@ -= Developer Introduction - -So you want to write a generator, fix a bug, or otherwise work with RDoc. This -document provides an overview of how RDoc works from parsing options to -generating output. Most of the documentation can be found in the specific -classes for each feature. - -== Bugs - -If you think you found a bug, file a ticket on the {issues -tracker}[https://github.com/ruby/rdoc/issues] on github. - -If your bug involves an error RDoc produced please include a sample file that -illustrates the problem or link to the repository or gem that is associated -with the bug. - -Please include steps to reproduce the issue. Here are some examples of good -issues: - -* https://github.com/ruby/rdoc/issues/55 -* https://github.com/ruby/rdoc/issues/61 - -== Developer Quick Start - -RDoc uses bundler for development. To get ready to work on RDoc run: - - $ gem install bundler - [...] - $ bundle install - [...] - $ rake - [...] - -This will install all the necessary dependencies for development with rake, -generate documentation and run the tests for the first time. - -If the 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 -(there shouldn't be). - -You can now use `rake` and `autotest` to run the tests. - -Note: the `rake` command must be used first before running any tests, because -it's used to generate various parsers implemented in RDoc. Also `rake clean` is -helpful to delete these generated files. - -== Glossary - -Here are definitions for some common terms in the RDoc documentation. The -list also briefly describes how the components of RDoc interact. - -parser:: - Parses files and creates a documentation tree from the contents. - -documentation tree:: - The documentation tree represents files, classes, modules, methods, - constants, includes, comments and other ruby syntax features as a tree. - RDoc walks this tree with a generator to create documentation. - -generator:: - Walks the documentation tree and generates output. - - RDoc ships with two generators, the Darkfish generator creates HTML and the - RI generator creates an RI data store. - -markup parser:: - Parses comments from a file into a generic markup tree. - - The markup parsers allow RDoc to handle RDoc, TomDoc, rd and Markdown format - documentation with common formatters. - -markup tree:: - Each parsed comment has a markup tree that represents common markup items - such as headings, paragraphs, lists or verbatim text sections for example - code or output. - - A generator uses a formatters to walks the tree to create output. Some - generators use multiple formatters on a markup tree to produce the output. - -formatter:: - Converts a parsed markup tree into some form other form of markup. - - Formatters can either produce a one-to-one conversion, such as ToHtml, or - extract part of the parsed result, such as ToHtmlSnippet which outputs the - first 100 characters as HTML. - -== Plugins - -When 'rdoc/rdoc' is loaded RDoc looks for 'rdoc/discover' files in your -installed gems. This can be used to load parsers, alternate generators, or -additional preprocessor directives. An rdoc plugin layout should look -something like this: - - lib/rdoc/discover.rb - lib/my/rdoc/plugin.rb - # etc. - -In your rdoc/discover.rb file you will want to wrap the loading of your plugin -in an RDoc version check like this: - - begin - gem 'rdoc', '~> 3' - require 'my/rdoc/plugin' - rescue Gem::LoadError - end - -=== Plugin Types - -In RDoc you can change the following behaviors: - -* Add a parser for a new file format -* Add a new output generator -* Add a new markup directive -* Add a new type of documentation markup -* Add a new type of formatter - -All of these are described below - -== Option Parsing - -Option parsing is handled by RDoc::Options. When you're writing a generator -you can provide the user with extra options by providing a class method -+setup_options+. The option parser will call this after your generator is -loaded. See RDoc::Generator for details. - -== File Parsing - -After options are parsed, RDoc parses files from the files and directories in -ARGV. RDoc compares the filename against what each parser claims it can parse -via RDoc::Parser#parse_files_matching. For example, RDoc::Parser::C can parse -C files, C headers, C++ files, C++ headers and yacc grammars. - -Once a matching parser class is found it is instantiated and +scan+ is called. -The parser needs to extract documentation from the file and add it to the RDoc -document tree. Usually this involves starting at the root and adding a class -or a module (RDoc::TopLevel#add_class and RDoc::TopLevel#add_module) and -proceeding to add classes, modules and methods to each nested item. - -When the parsers are finished the document tree is cleaned up to remove -dangling references to aliases and includes that were not found (and may exist -in a separate library) through RDoc::ClassModule#complete. - -To write your own parser for a new file format see RDoc::Parser. - -=== Documentation Tree - -The parsers build a documentation tree that is composed of RDoc::CodeObject and -its subclasses. There are various methods to walk the tree to extract -information, see RDoc::Context and its subclasses. - -Within a class or module, attributes, methods and constants are divided into -sections. The section represents a functional grouping of parts of the class. -TomDoc uses the sections "Public", "Internal" and "Deprecated". The sections -can be enumerated using RDoc::Context#each_section. - -== Output Generation - -An RDoc generator turns the documentation tree into some other kind of output. -RDoc comes with an HTML generator (RDoc::Generator::Darkfish) and an RI -database generator (RDoc::Generator::RI). The output a generator creates does -not have to be human-readable. - -To create your own generator see RDoc::Generator. - -=== Comments - -In RDoc 3.10 and newer the comment on an RDoc::CodeObject is now an -RDoc::Comment object instead of a String. This is to support various -documentation markup formats like rdoc, TomDoc and rd. The comments are -normalized to remove comment markers and remove indentation then parsed lazily -via RDoc::Comment#document to create a generic markup tree that can be -processed by a formatter. - -To add your own markup format see RDoc::Markup@Other+directives - -==== Formatters - -To transform a comment into some form of output an RDoc::Markup::Formatter -subclass is used like RDoc::Markup::ToHtml. A formatter is a visitor that -walks a parsed comment tree (an RDoc::Markup::Document) of any format. To help -write a formatter RDoc::Markup::FormatterTestCase exists for generic parsers, -and RDoc::Markup::TextFormatterTestCase which contains extra test cases for -text-type output (like +ri+ output). - -RDoc ships with formatters that will turn a comment into HTML, rdoc-markup-like -text, ANSI or terminal backspace highlighted text, HTML, cross-referenced HTML, -an HTML snippet free of most markup, an HTML label for use in id attributes, a -table-of-contents page, and text with only code blocks. - -The output of the formatter does not need to be text or text-like. -RDoc::Markup::ToLabel creates an HTML-safe label for use in an HTML id -attribute. A formatter could count the number of words and the average word -length for a comment, for example. - -==== Directives - -For comments in markup you can add new directives (:nodoc: is a directive). -Directives may replace text or store it off for later use. - -See RDoc::Markup::PreProcess::register for details. - -=== JSONIndex - -RDoc contains a special generator, RDoc::Generator::JSONIndex, which creates a -JSON-based search index and includes a search engine for use with HTML output. -This generator can be used to add searching to any HTML output and is designed -to be called from inside an HTML generator. - -== Markup - -Additional documentation markup formats can be added to RDoc. A markup -parsing class must respond to \::parse and accept a String argument containing -the markup format. An RDoc::Document containing documentation items -(RDoc::Markup::Heading, RDoc::Markup::Paragraph, RDoc::Markup::Verbatim, etc.) -must be returned. - -To register the parser with rdoc, add the markup type's name and class to the -RDoc::Text::MARKUP_FORMAT hash like: - - RDoc::Text::MARKUP_FORMAT['rdoc'] = RDoc::Markup diff --git a/README.md b/README.md index fcabeeb259..f994820832 100644 --- a/README.md +++ b/README.md @@ -99,7 +99,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 diff --git a/rdoc.gemspec b/rdoc.gemspec index 039e27a16d..ada9341fda 100644 --- a/rdoc.gemspec +++ b/rdoc.gemspec @@ -38,7 +38,7 @@ RDoc includes the +rdoc+ and +ri+ tools for generating and displaying documentat # for ruby core repository. It was generated by # `git ls-files -z`.split("\x0").each {|f| puts " #{f.dump}," unless f.start_with?(*%W[test/ spec/ features/ .]) } non_lib_files = [ - "CONTRIBUTING.rdoc", + "CONTRIBUTING.md", "CVE-2013-0256.rdoc", "ExampleMarkdown.md", "ExampleRDoc.rdoc",