(https://github.com/ruby/rdoc/pull/1176)
* Move method source block to the top
Currently, if a method description is long (e.g. `Array.new`), users need
to click the method toggle button next to the method title, and then scroll
down to the source code expanded below the description.
This commit changes the behavior so that the source code is expanded
immediately below the method title.
* Update method toggle's interface
1. Display the method toggle button by default instead of displaying on hover
2. Only toggle the source code when clicking the method toggle button, not
when clicking the entire method title section. This will allow us to display
an anchor link next to the method title
3. Simplify the toggle source button's appearance
* Use details tag for method toggling
* Rename method-click-advice to method-source-toggle
* Improve method controls' display on mobile
By moving the method controls out of the method header, we can display
them to the right of the method name on desktop, and below the method name
on mobile.
* Add "Example" label to example code blocks
The label should help users distinguish example code blocks from other
code blocks, such as method source code.
It's only applied to Ruby code examples.
* Revert "Add "Example" label to example code blocks"
This reverts commit https://github.com/ruby/rdoc/commit/69fc9ce6a379.
* Give source code blocks a different background color
* Change targeted method's highlighting color to work better with the new method source
https://github.com/ruby/rdoc/commit/e608a84af3
expanded
(https://github.com/ruby/rdoc/pull/1181)
Something that's been bothering me is that while the source code is
not visible by default, the browser still jump to it when searching.
Adding the `visible` property prevents this.
Test it out yourself:
* `bundle exec rdoc`
* open `_site/index.html`
* Search for `NameError`
Before, you will get a match from `load_yaml` source code, after
you only get the match when that methods source code is expanded.
https://github.com/ruby/rdoc/commit/003126cc23
* `rake install` command is failed
\### Problems
Several file paths were changed by following PR.
- 4211292ffe
- d7bca12c13
Because rdoc.gemspec doesn't take in this changes,
the `rake install` command is permanently failed.
\### Test
\#### before
```console
❯ bundle exec rake install
Running RuboCop...
Inspecting 4 files
....
4 files inspected, no offenses detected
Tip: Based on detected gems, the following RuboCop extension libraries
might be helpful:
* rubocop-rake (https://rubygems.org/gems/rubocop-rake)
You can opt out of this message by adding the following to your config
(see
https://docs.rubocop.org/rubocop/extensions.html#extension-suggestions
for more options):
AllCops:
SuggestExtensions: false
rake aborted!
Running `gem build -V
/Users/mterada/dev/redDataTools/remove_dependency/rdoc/rdoc.gemspec`
failed with the following output:
WARNING: See https://guides.rubygems.org/specification-reference/ for
help
ERROR: While executing gem ... (Gem::InvalidSpecificationException)
["RI.rdoc", "lib/rdoc/alias.rb", "lib/rdoc/anon_class.rb",
"lib/rdoc/any_method.rb", "lib/rdoc/attr.rb",
"lib/rdoc/class_module.rb", "lib/rdoc/constant.rb",
"lib/rdoc/context.rb", "lib/rdoc/context/section.rb",
"lib/rdoc/extend.rb", "lib/rdoc/ghost_method.rb", "lib/rdoc/include.rb",
"lib/rdoc/meta_method.rb", "lib/rdoc/method_attr.rb",
"lib/rdoc/mixin.rb", "lib/rdoc/normal_class.rb",
"lib/rdoc/normal_module.rb", "lib/rdoc/require.rb",
"lib/rdoc/single_class.rb", "lib/rdoc/top_level.rb"] are not files
/Users/mterada/.rbenv/versions/3.1.0/bin/bundle:25:in `load'
/Users/mterada/.rbenv/versions/3.1.0/bin/bundle:25:in `<main>'
Tasks: TOP => install => build
(See full trace by running task with --trace)
```
\#### after
```console
❯ bundle exec rake install
Running RuboCop...
Inspecting 4 files
....
4 files inspected, no offenses detected
Tip: Based on detected gems, the following RuboCop extension libraries might be helpful:
* rubocop-rake (https://rubygems.org/gems/rubocop-rake)
You can opt out of this message by adding the following to your config (see https://docs.rubocop.org/rubocop/extensions.html#extension-suggestions for more options):
AllCops:
SuggestExtensions: false
rdoc 6.7.0 built to pkg/rdoc-6.7.0.gem.
rdoc (6.7.0) installed.
```
* Add a `bundle exec rake install` step to github workflow
* make intentionally CI failed
* Revert "make intentionally CI failed"
This reverts commit 9fc5dd9423a024594ad26d86a8a6af829e7017f8.
(https://github.com/ruby/rdoc/pull/1157)
- Update color scheme with muted green tones and improved contrast
- Enhance readability by adjusting font sizes and weights
- Improve code block styling with a light gray background
- Refactor layout for better responsiveness and sidebar presentation
- Standardize link styles across the document
- Implement CSS variables for easier theme customization
- Adjust heading styles for better visual hierarchy
- Enhance table and list styling for improved readability
- Optimize search field and navigation toggle appearance
- Improve method detail and documentation section styling
- Reorganize css and overhaul the sidebar design
- Improve code block's syntax highlighting
https://github.com/ruby/rdoc/commit/6cde9edadb
Avoids warnings like
```
/path/to/ruby/3.3.4/lib/ruby/gems/3.3.0/gems/rbs-3.4.0/lib/rdoc/discover.rb:10: warning: method redefined; discarding old scan
/path/to/ruby/3.3.4/lib/ruby/gems/3.3.0/gems/rbs-3.5.1/lib/rdoc/discover.rb:10: warning: previous definition of scan was here
```
https://github.com/ruby/rdoc/commit/e47920d8f3
(https://github.com/ruby/rdoc/pull/1154)
* Add missing footers
In #1152 the footer partial was only added to the index.rhtml file.
This commit adds the footer partial to the other template files.
* Remove unnecessary middle divs in nav
* Simplify sidebar's overflow settings
Because sidebar needs to be scrollable, its overflow should default to auto.
Currently it's set to hidden and force individual elements to set overflow auto,
which overcomplicates things.
https://github.com/ruby/rdoc/commit/b8c2bcd8db
(https://github.com/ruby/rdoc/pull/1144)
* Add a new ruby parser RDoc::Parser::PrismRuby
* Add a new ruby parser testcase independent from parser's internal implementation
* unknown meta method
* Use MethodSignatureVisitor only to scan params, block_params and calls_super
* Add calls_super test
* Drop ruby 2.6. Prism requires ruby >= 2.7
* Remove duplicated documentation comment from prism_ruby.rb
* Add test for wrong argument passed to metaprogramming method
* Rename visit_call_[DSL_METHOD_NAME] to make it distinguishable from visit_[NODE_TYPE]_node
* Method receiver switch of true/false/nil to a case statement
* Extract common part of add_method(by def keyword) and add meta_comment method
* Reuse consecutive comments array when collecting comments
* Simplify DSL call_node handling
* Refactor extracting method visibility arguments
https://github.com/ruby/rdoc/commit/fde99f1be6
While writing some Markdown documentation for Rails, I came across an
interesting case where trying to link to an instance method at the start
of a line would instead parse as an H1 heading:
```markdown
#response_body=
```
Expected:
```html
<a href=""><code>#response_body=</code></a>
```
Actual:
```html
<h1>response_body=</h1>
```
According to the CommonMark spec:
> At least one space or tab is required between the # characters and the
> heading’s contents, unless the heading is empty. Note that many
> implementations currently do not require the space. However, the space
> was required by the original ATX implementation, and it helps prevent
> things like the following from being parsed as headings:
>
> Example 64
So while some implementations do not follow this requirement, I believe
RDoc should because it makes it easy to write text similar to Example 64
(which was used in the new test) and it also enables automatically
linking to instance methods at the start of a line.
(https://github.com/ruby/rdoc/pull/1118)
* Drop reimplementation of Ripper lex state
This code was for ruby 2.4 compatibility, but rdoc dropped support for
ruby 2.4 about three years ago, in f480b970c. This code was almost half
of the lines of code in rdoc/parser/ripper_state_lex.
* Remove unused Ripper constants and const_defined?
This was mostly copied from the diff in @st0012's PR comment. The
remaining constants have been updated to get their value directly from
Ripper.
Co-authored-by: Stan Lo <stan001212@gmail.com>
* Use Ripper::EXPR_LABEL directly
Since this is only used from outside RipperStateLex, there's no longer
any benefit to using the indirect reference rather than just going
straight to Ripper.
---------
https://github.com/ruby/rdoc/commit/dd8c216263
Co-authored-by: Stan Lo <stan001212@gmail.com>
With verbopse mode (-w), the interpreter shows a warning if
a block is passed to a method which does not use the given block.
Warning on:
* the invoked method is written in C
* the invoked method is not `initialize`
* not invoked with `super`
* the first time on the call-site with the invoked method
(`obj.foo{}` will be warned once if `foo` is same method)
[Feature #15554]
`Primitive.attr! :use_block` is introduced to declare that primitive
functions (written in C) will use passed block.
For minitest, test needs some tweak, so use
ea9caafc07
for `test-bundled-gems`.
Previously, any sort of "rich" markup for a definition list's label
would cause the Markdown parser to not recognize a definition list:
```ruby
md = <<~md
`one`
: This is a definition
md
doc = RDoc::Markdown.parse(md)
doc # => [doc: [para: "<code>one</code>\n: This is a definition"]]
```
This commit tweaks the grammar for Markdown definition lists so that
labels can include "rich" markup such as bold (`**`), code (```), etc:
```ruby
md = <<~md
`one`
: This is a definition
md
doc = RDoc::Markdown.parse(md)
doc # => [doc: [list: NOTE [item: ["<code>one</code>"]; [para: "This is a definition"]]]]
```
The [PHP Markdown Extra][1] Spec does not seem to specify whether or not
this should be allowed, but it is allowed in the RDoc format:
```ruby
rdoc = <<~rdoc
+code+::
This is a definition
rdoc
doc = RDoc::Markup.parse(rdoc)
doc # => [doc: [list: NOTE [item: ["+code+"]; [para: "This is a definition"]]]]
```
so accepting this change increases the parity of the two formats.
[1]: https://michelf.ca/projects/php-markdown/extra/#def-listhttps://github.com/ruby/rdoc/commit/8f943bbba4
Previously, trying to round-trip label-list and name-lists with the
ToRdoc converter was not possible:
```ruby
doc = <<~RDOC
foo ::
bar ::
hi
RDOC
markup = RDoc::Markup.parse(doc)
markup # => [doc: [list: NOTE [item: ["foo ", "bar"]; [para: "hi"]]]]
rt = RDoc::Markup::ToRdoc.new.convert(markup)
rt # => "foo\nbar:\n hi\n\n"
rt_markup = RDoc::Markup.parse(rt)
rt_markup # => [doc: [para: "foo ", "bar:"], [verb: "hi\n"]]
```
This commit addresses the issue by fixing ToRdoc to generate output that
can be properly reparsed by RDoc. ToRdoc tests additionally needed to be
updated for the new output.
The old implementation of `accept_list_item_start` was copied to ToBs
because those tests did not pass with the new changes and I am
unfamiliar with the `backspace` format.
After:
```ruby
doc = <<~RDOC
foo ::
bar ::
hi
RDOC
markup = RDoc::Markup.parse(doc)
markup # => [doc: [list: NOTE [item: ["foo ", "bar"]; [para: "hi"]]]]
rt = RDoc::Markup::ToRdoc.new.convert(markup)
rt # => "foo::\nbar::\n hi\n\n"
rt_markup = RDoc::Markup.parse(rt)
rt_markup # => [doc: [list: NOTE [item: ["foo", "bar"]; [para: "hi"], blankline]]]
```
https://github.com/ruby/rdoc/commit/c6c51aa900
Previously, using ToMarkdown on a label-list would generate output that
could not be reparsed by the RDoc::Markdown parser:
```
md = <<~MD
apple
: a red fruit
banana
: a yellow fruit
MD
doc = RDoc::Markdown.parse(md)
doc # => [doc: [list: NOTE [item: ["apple"]; [para: "a red fruit"]], [item: ["banana"]; [para: "a yellow fruit"]]]]
new_md = doc.accept(RDoc::Markup::ToMarkdown.new)
new_md # => "apple\n: a red fruit\nbanana\n: a yellow fruit\n\n"
new_doc = RDoc::Markdown.parse(new_md)
new_doc # => [doc: [list: NOTE [item: ["apple"]; [para: "a red fruit\nbanana\n: a yellow fruit"]]]]
```
The issue is that the [PHP Markdown Extra spec][1] requires a newline
after each definition list item, but ToMarkdown was not putting newlines
between label-list items.
This commit fixes the issue by properly appending a newline after each
label-list item so that the output of ToMarkdown can be reparsed by
RDoc::Markdown:
```
md = <<~MD
apple
: a red fruit
banana
: a yellow fruit
MD
doc = RDoc::Markdown.parse(mdoc)
doc # => [doc: [list: NOTE [item: ["apple"]; [para: "a red fruit"]], [item: ["banana"]; [para: "a yellow fruit"]]]]
new_md = doc.accept(RDoc::Markup::ToMarkdown.new)
new_md # => "apple\n: a red fruit\n\nbanana\n: a yellow fruit\n\n"
new_doc = RDoc::Markdown.parse(new_md)
new_doc # => [doc: [list: NOTE [item: ["apple"]; [para: "a red fruit"]], [item: ["banana"]; [para: "a yellow fruit"]]]]
```
[1]: https://michelf.ca/projects/php-markdown/extra/#def-listhttps://github.com/ruby/rdoc/commit/c65266437c
Attribute readers and writers can be marked as `:nodoc` to keep them
undocumented:
```ruby
attr_reader :name # :nodoc:
```
For aliases this behaviour should be the same:
```ruby
alias_method :old :new # :nodoc:
```
https://github.com/ruby/rdoc/commit/30f14e8271
Even for singleton class definition such as `class << self` that
shares the same container with the outer scope, its visibility is
separated and set to `public` by default.
https://github.com/ruby/rdoc/commit/baf26363b9
Each singleton method definition of the form `def recv.method` has
visibility separate from the outer scope and is set to `public` by
default.
https://github.com/ruby/rdoc/commit/810913a7ea
`@locale` is set from `@locale_name` and loaded from `@locale_dir`
after `write_options`, and `RDoc::I18n::Locale` does not seem to
expected to be loaded.
https://github.com/ruby/rdoc/commit/fd610f7023
Stan Lo
Sam Bostock
tomoya ishida
Earlopain
Mads Ohm Larsen
mterada1228
Ufuk Kayserilioglu
Hiroshi SHIBATA
David Rodríguez
Stan Lo
Burdette Lamar
Hartley McGuire
nicholas a. evans
Yudai Takada
Adam Daniels
Koichi Sasada
Nobuyoshi Nakada
Petrik