Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Remove Reference from config #2049

Open
wants to merge 1 commit into
base: master
Choose a base branch
from

Conversation

Earlopain
Copy link
Contributor

On https://docs.rubocop.org/rubocop-rspec/3.5/cops_rspec.html, every cop has a reference section, linking to the same text on rubydoc. It also doesn't render very well, ` for example is just taken as is.

The reference section is intended for style guide urls and other extra reading for specific cops. I don't think linking to rubydoc provides much value, it just dilutes the actual references, so maybe we can just remove them?


Before submitting the PR make sure the following are checked:

  • Feature branch is up-to-date with master (if not - rebase it).
  • Squashed related commits together.
  • Added tests.
  • Updated documentation.
  • Added an entry to the CHANGELOG.md if the new code introduces user-observable changes.
  • The build (bundle exec rake) passes (be sure to run this locally, since it may produce updated documentation that you will need to commit).

If you have created a new cop:

  • Added the new cop to config/default.yml.
  • The cop is configured as Enabled: pending in config/default.yml.
  • The cop is configured as Enabled: true in .rubocop.yml.
  • The cop documents examples of good and bad code.
  • The tests assert both that bad code is reported and that good code is not reported.
  • Set VersionAdded: "<<next>>" in default/config.yml.

If you have modified an existing cop's configuration options:

  • Set VersionChanged: "<<next>>" in config/default.yml.

On https://docs.rubocop.org/rubocop-rspec/3.5/cops_rspec.html, every cop has a reference
section, linking to the same text on rubydoc.

The reference section is intended for style guide urls and other extra reading for specific cops.
I don't think linking to rubydoc provides much value, it just dilutes the actual references, so
maybe we can just remove them?
@Earlopain Earlopain requested a review from a team as a code owner February 19, 2025 18:58
@bquorning
Copy link
Collaborator

The links were added in #430, arguing that

This is great for IDE/text editor integration and means that users don't have to copy/paste RSpec/CopName into Google to find documentation. Because you guys already use RubyDoc, we basically get this for free.

Perhaps we can keep the links, but just not render them in the HTML docs?

@Earlopain
Copy link
Contributor Author

The proper place for that nowadays is Cop.documentation_url. ruby-lsp for example uses it to link to first-party docs on offenses:
image

You get this for free by defining DocumentationBaseURL here:

DocumentationBaseURL: https://docs.rubocop.org/rubocop-rspec

I didn't find an option to output this link on cli for offenses but there probably is one and I missed it? There is --show-docs-url but that just shows the links without actually running it.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants