(https://github.com/ruby/rdoc/pull/1141)
There have been several document refactors in ruby/ruby that extract
individual methods/classes' documentation into separate files, like
ruby/ruby#6567
Because RI is not capable of rendering those references, RI users
are left with dramatically fewer documentation on those methods/classes.
This commit adds a new option `--expand-ref` (default: true) to expand
all the rdoc-ref targets at the end of the output.
9e2b28c6e3
(https://github.com/ruby/rdoc/pull/1137)
This is an attempt to utilize RuboCop further.
RuboCop was added in 9262fdd43a
but only a few rules have been enabled.
I believe we can utilize RuboCop more for better code quality,
especially with Lint cops.
This is the first step to enable other Lint cops.
This commit also exclude some auto generated files.
a53287fce0
(https://github.com/ruby/rdoc/pull/1209)
* Use the original `label` description list style
As a default for all description lists, the original "label" style is
more readable.
This is slightly different from the original `label` dl though:
* slightly increased left margin for `dd` (to 1em)
* removed right margin on `dd`
* removed `dt` bottom margin and `dd` top margin, to reduce the gap
between the term and its description (to only the standard line-height
gap).
* Add closing tags for description list terms
Without the closing tags, the dt elements contain whitespace after the
text. This normally isn't a big deal, but does mess some things up,
e.g: using `::after` with `content: ", "` in stylesheets.
* Restore float:left style for note lists
Unlike the original note list styles, this version sets the line-height
for all `dt` elements to be the same as the `p` elements contained
inside the `dd`, so that the second line has the same indentation as all
subsequent lines.
* Add commas between note list terms
9e69ea6d75
argument
(https://github.com/ruby/rdoc/pull/1222)
It is necessary for ClassModule's instance variable @superclass to
always be a String (or nil) so that the class can be saved with
`#marshal_dump` and loaded with `#marshal_load`.
However, there's no type checking being done, which allows a bug like
the one reported in #1221 (which was introduced in #1217) that sets
superclass to a ClassModule. That bug requires:
- setting a superclass to a NormalClass
- marshal_save
- marshal_load (which raises an exception)
With this change, passing a ClassModule to ClassModule#superclass= is
explicitly allowed by saving the full name of the ClassModule in the
@superclass instance variable.
9ced6d534c
This reverts commit 2923f42ed7.
3375565361 (step):23:1031
```
/home/runner/work/actions/actions/snapshot-master/lib/rdoc/code_object.rb:322:in 'RDoc::CodeObject#parent': undefined method 'find_class_or_module' for nil (NoMethodError)
from /home/runner/work/actions/actions/snapshot-master/lib/rdoc/code_object/class_module.rb:342:in 'RDoc::ClassModule#marshal_dump'
from /home/runner/work/actions/actions/snapshot-master/lib/rdoc/store.rb:878:in 'Marshal.dump'
from /home/runner/work/actions/actions/snapshot-master/lib/rdoc/store.rb:878:in 'block in RDoc::Store#save_class'
from /home/runner/work/actions/actions/snapshot-master/lib/rdoc/store.rb:877:in 'IO.open'
from /home/runner/work/actions/actions/snapshot-master/lib/rdoc/store.rb:877:in 'RDoc::Store#save_class'
from /home/runner/work/actions/actions/snapshot-master/lib/rdoc/store.rb:763:in 'block in RDoc::Store#save'
from /home/runner/work/actions/actions/snapshot-master/lib/rdoc/store.rb:762:in 'Array#each'
from /home/runner/work/actions/actions/snapshot-master/lib/rdoc/store.rb:762:in 'RDoc::Store#save'
from /home/runner/work/actions/actions/snapshot-master/lib/rdoc/generator/ri.rb:27:in 'RDoc::Generator::RI#generate'
from /home/runner/work/actions/actions/snapshot-master/lib/rdoc/rdoc.rb:528:in 'block in RDoc::RDoc#generate'
from /home/runner/work/actions/actions/snapshot-master/lib/rdoc/rdoc.rb:522:in 'Dir.chdir'
from /home/runner/work/actions/actions/snapshot-master/lib/rdoc/rdoc.rb:522:in 'RDoc::RDoc#generate'
from /home/runner/work/actions/actions/snapshot-master/lib/rdoc/rdoc.rb:501:in 'RDoc::RDoc#document'
from ./tool/rdoc-srcdir:27:in '<main>'
```
(https://github.com/ruby/rdoc/pull/1219)
There are three distinct ranges of symbols in ASCII:
- the range below "A", 0..64 in decimal
- the range between "Z" and "a", 91..96 in decimal
- the range above "z", 123..127 in decimal
With this change, any method starting with a character in these
"symbol ranges" will be sorted before a method starting with an alpha
ASCII character. The remaining methods, all starting with alpha or
8-bit characters, will be sorted against each other exactly as before.
Specifically this addresses the issue from #1204 which is that `#[]`
and `#^` were previously sorted _after_ the alpha methods. These
methods will now be sorted before alpha methods.
Fixes https://github.com/ruby/rdoc/pull/1204a4f13d242b
(https://github.com/ruby/rdoc/pull/1212)
Currently, the gemspec's files are defined by hand, which is error-prone.
For example: https://github.com/ruby/rdoc/pull/1211
This commit uses `Dir.glob` where possible to reduce the risk of that
happening again.
- Additional files added with this approach:
```
# This should have been added by only captured by this commit
lib/rdoc/parser/prism_ruby.rb
# These are folders and can be included/ignored either way
lib/rdoc/generator/template/darkfish
lib/rdoc/generator/template/darkfish/css
lib/rdoc/generator/template/darkfish/fonts
lib/rdoc/generator/template/darkfish/images
lib/rdoc/generator/template/darkfish/js
lib/rdoc/generator/template/json_index
lib/rdoc/generator/template/json_index/js
```
- Files that are ignored after this change:
```
# They make no difference on documentation generation
# Probably can be removed
lib/rdoc/generator/template/darkfish/.document
lib/rdoc/generator/template/json_index/.document
```
ac2a151f10
(https://github.com/ruby/rdoc/pull/1191)
* Cleanup rdoc.css
* Use red as the highlight color
* Use the same red as ruby-lang.org
* Make main section links stand out more
* Remove scrollbar styling
f69dc470ac
`--embed-mixins`
(https://github.com/ruby/rdoc/pull/842)
* Embed mixed-in methods and constants with `--embed-mixins`
When `--embed-mixins` option is set:
- methods from an `extend`ed module are documented as singleton methods
- attrs from an `extend`ed module are documented as class attributes
- methods from an `include`ed module are documented as instance methods
- attrs from an `include`ed module are documented as instance attributes
- constants from an `include`ed module are documented
Sections are created when needed, and Darkfish's template annotates
each of these mixed-in CodeObjects. We also respect the mixin methods'
visibility.
This feature is inspired by Yard's option of the same name.
* Add comment to document why we set object visibility
Co-authored-by: Stan Lo <stan001212@gmail.com>
* Add the mixin_from attribute to CodeObject's initializer
* Add test coverage for private mixed-in attributes.
---------
481c2ce660
Co-authored-by: Stan Lo <stan001212@gmail.com>
(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 69fc9ce6a3.
* Give source code blocks a different background color
* Change targeted method's highlighting color to work better with the new method source
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.
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.
devices
(https://github.com/ruby/rdoc/pull/1162)
- Make the sidebar toggle fixed on all devices
- Prevent default zooming on mobile devices
- Improve sidebar opening on mobile devices
95b6cfb64f
(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
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
```
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.
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
fde99f1be6
method.
(https://github.com/ruby/rdoc/pull/1135)
* Unify top_level creation in tests
* Remove unnecessary file_name param from Parser.for
It should be always the same as the top_level's absolute_name, so there's
no point of taking it as a separate parameter.
97c497dfbb
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/1139)
* Rename rake rubocop to rake format_generated_files
* Add rubocop rules to ensure spaces are applied consistently
* Improve rubocop related CI workflows
27932d001c
(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.
---------
dd8c216263
Co-authored-by: Stan Lo <stan001212@gmail.com>
(https://github.com/ruby/rdoc/pull/1114)
It's hard to distinguish code object classes by their file names alone.
And given that we have 18 such classes, it'd make the codebase a lot
easier to understand if we grouped them into a single directory.
Given that these classes are all autoloaded in `lib/rdoc.rb` instead
of required individually, this change should have minimum impact on
projects using RDoc as they generally just require `rdoc`, not individual
files. An example is Rails' `sdoc`:
https://github.com/rails/sdoc/blob/main/lib/sdoc/rdoc_monkey_patches.rb4211292ffe
