-
-
Notifications
You must be signed in to change notification settings - Fork 41
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
Update doc with updated yard #131
Conversation
I checked many pages and didn't find any visual regression. |
bundle exec rake "update_docs[3.9, enable-yard-and-bump-doc]" Switch to maintenance branch
8a499e3
to
b5d6c5d
Compare
Initial PR has been updated with new rake command. The doc is now generated using 3-9-maintenance branchs + yard update. |
@benoittgt We have the staging site so if you're confident your PRs are ok we should add them here, merge and deploy to staging, then maybe run |
Percy is a good idea. I looked at it. I think it will require a little bit of setup. Their is a lot of visual changes with the frame (left menu) and various CSS adjustments. I would love to have a clear output from Percy. Not too polluted by the left menu frame. I will give a better try tomorrow. At the moment I have something that not really help us 😅: EDIT: Source of the local build https://percy.io/RSpec/rspec.github.io/builds/3633498 |
Ok I tried https://github.com/evolvingweb/sitediff and https://code.google.com/archive/p/daisydiff/ but their too many noise in diff. What can I do is a visual review of each page side by side. If you think it's ok @JonRowe tell me. Also if you can tell me what you want to do with:
|
I will try to do it before this week-end to close all related PR. |
Personally I think the solution is to write a script with nokogiri to pull out the text and diff it that way, we don't care about HTML changes just content changes. I also don't want to change the index readme |
Hello I worked on very basic script that will generate a text diff between two version of the yard documentation. https://github.com/benoittgt/sitediff_rspec The script removes part of the documentation to avoid some noise. For example:
I also disable all
I only worked on one page at the moment. So their is probably more surprise in other pages. I am wondering. How much we want to customize the script to get as low as possible of unrelevant differences. It will needs special rules for each of differences. For example: - - (Object) render_views=render_views=(val) - (Object) render_views=(val)
+ #render_views=render_views=(val) ⇒ Object #render_views=(val) ⇒ Object I stop it to ask for a first feedback before going further. Thanks 😊 |
I love this approach @benoittgt great work, theres some bits wrong in some of the diffs: defdef selfself..add_test_type_configurationsadd_test_type_configurations((configconfig))
- configconfig..includeinclude RSpecRSpec::::RailsRails::::ControllerExampleGroupControllerExampleGroup,, :type:type =>=> :controller:controller
- configconfig..includeinclude RSpecRSpec::::RailsRails::::HelperExampleGroupHelperExampleGroup,, :type:type =>=> :helper:helper
- configconfig..includeinclude RSpecRSpec::::RailsRails::::ModelExampleGroupModelExampleGroup,, :type:type =>=> :model:model
- configconfig..includeinclude RSpecRSpec::::RailsRails::::RequestExampleGroupRequestExampleGroup,, :type:type =>=> :request:request
- configconfig..includeinclude RSpecRSpec::::RailsRails::::RoutingExampleGroupRoutingExampleGroup,, :type:type =>=> :routing:routing
- configconfig..includeinclude RSpecRSpec::::RailsRails::::ViewExampleGroupViewExampleGroup,, :type:type =>=> :view:view
- configconfig..includeinclude RSpecRSpec::::RailsRails::::FeatureExampleGroupFeatureExampleGroup,, :type:type =>=> :feature:feature
- configconfig..includeinclude RSpecRSpec::::RailsRails::::MatchersMatchers
- configconfig..includeinclude RSpecRSpec::::RailsRails::::SystemExampleGroupSystemExampleGroup,, :type:type =>=> :system:system
+ configconfig..includeinclude RSpecRSpecRSpecRSpec::::RailsRailsRailsRails::::ControllerExampleGroupControllerExampleGroupControllerExampleGroupControllerExampleGroup,, :type:type =>=> :controller:controller
+ configconfig..includeinclude RSpecRSpecRSpecRSpec::::RailsRailsRailsRails::::HelperExampleGroupHelperExampleGroupHelperExampleGroupHelperExampleGroup,, :type:type =>=> :helper:helper
+ configconfig..includeinclude RSpecRSpecRSpecRSpec::::RailsRailsRailsRails::::ModelExampleGroupModelExampleGroupModelExampleGroupModelExampleGroup,, :type:type =>=> :model:model
+ configconfig..includeinclude RSpecRSpecRSpecRSpec::::RailsRailsRailsRails::::RequestExampleGroupRequestExampleGroupRequestExampleGroupRequestExampleGroup,, :type:type =>=> :request:request
+ configconfig..includeinclude RSpecRSpecRSpecRSpec::::RailsRailsRailsRails::::RoutingExampleGroupRoutingExampleGroupRoutingExampleGroupRoutingExampleGroup,, :type:type =>=> :routing:routing
+ configconfig..includeinclude RSpecRSpecRSpecRSpec::::RailsRailsRailsRails::::ViewExampleGroupViewExampleGroupViewExampleGroupViewExampleGroup,, :type:type =>=> :view:view
+ configconfig..includeinclude RSpecRSpecRSpecRSpec::::RailsRailsRailsRails::::FeatureExampleGroupFeatureExampleGroupFeatureExampleGroupFeatureExampleGroup,, :type:type =>=> :feature:feature
+ configconfig..includeinclude RSpecRSpecRSpecRSpec::::RailsRailsRailsRails::::MatchersMatchersMatchersMatchers
+ configconfig..includeinclude RSpecRSpecRSpecRSpec::::RailsRailsRailsRails::::SystemExampleGroupSystemExampleGroupSystemExampleGroupSystemExampleGroup,, :type:type =>=> :system:system
endend# File 'lib/rspec/rails/configuration.rb', line 43 |
Sorry @JonRowe. Their is "big" change in yard doc. "method summary" are moved at the end of the documentation. You have to click on it. Left updated yard | Right current yard At the end of doc you can get details. |
I will switch the script to check all the page of current yard and will inspect diff. 😱 |
You are completely right Jon. Sorry. |
No need to apologise, thank you for looking at this! |
So for this. In the new website, object class are links and in the old website we do not have the link. I am using New website: <span class="const"> <!-- node.test -> "Rspec" -->
<span class="object_link"> <!-- node.test -> "Rspec" -->
<a href="../RSpec.html" title="RSpec (module)">RSpec</a> <!-- node.test -> "Rspec" -->
</span>
</span> Old yard: <span class="const">RSpec</span> 2 `"RSpec" will be added to text output. I have changed a lot the script to make the diff. I will publish my findings today. I will handle this special case too. |
Ok So I had to remove few things to get not too noisy diff. https://github.com/benoittgt/sitediff_rspec/blob/master/README.md#elements-in-yard-doc-altered The full diff is here: https://github.com/benoittgt/sitediff_rspec/blob/master/README.md#output There is still some wrong diff that produce unrealevant noise. I will dig into that diff tomorrow and tell you if I see something that should be discussed. To do:
|
The index doc in yard doc was README.md in all rspec repos expect rspec-rails where is was README-DEV.md. I think we should switch to README.md to all repos. |
I agree |
Command from rspec-dev: ``` rvm use 2.7 && export USE_GIT_REPOS=1 && export RAILS_VERSION='~>6.0' && bundle exec rake "update_docs[3.9, enable-yard-and-bump-doc]" ```
There is something weird from yard or maybe from us. #... separate custom file using the --options command-line parameter. Yard display It is not happening everywhere. This should normally not happen because we have in
and we have also another I tried to reproduce locally without success. # `--only-failures` and --next-failure
class WebServer
# `--only-failures` and --next-failure
def get(request) "hello" end
end
Without |
Also with the code: def reporter
# @reporter_buffer should only ever be set in this method to cover
# initialization of @reporter. First comment line have carriage return removed. |
There is a big removal of the comment from It seems to be linked to lsegal/yard#1173 but I do not understand why it is not working anymore. 🤔 |
Again "Overview" rely on a different part. It seems a similar issue to #131 (comment) |
@lsegal by any chance do you have ideas for the last 4 comments? Thanks |
For #131 (comment) and the weird BTW. I will keep a to do list on the initial PR body. To follow the remaining tasks. |
From rspec-dev folder `bundle exec rake run["bundle update redcarpet"]`
Saw your issue in YARD, and ended up here. The problem above with
Really, the comment for the I think it's a little different than the YARD issue, as the above code line isn't parsed by YARD. JFYI, for a long time, everything was stable. Then RDoc switched from using their own Ruby parser to Ripper, and small changes have been made to Ripper (which really didn't care about comments) that have resulted in small breakages to YARD based doc systems... |
Thank you very much @MSP-Greg. I tried to add one line on --- a/lib/rspec/core/formatters.rb
+++ b/lib/rspec/core/formatters.rb
@@ -1,3 +1,4 @@
+
RSpec::Support.require_rspec_support "directory_maker" But I am trying to fix this for example this part: Who is different. I am gonna look at Ripper. |
Just to be clear, the added line in formatters.rb needs to go between the first code line and the comments that are after it. Re the problem with the But, I've got a lot patches to try to allow parsing RDoc style comments for Ruby docs, etc. I'm also using CommonMarker, but that shouldn't affect the code block issue... |
Thanks I'm gonna take a look. In the meantime I remove the most code I could to have a very basic reproduction case https://github.com/benoittgt/rspec-core/tree/only-configuration-reporter Thanks a lot for your help @MSP-Greg. Very appreciated |
There is probably an issue with Ripper since Ruby 2.7. https://redmine.ruby-lang.org/issues/16675 I will probably generate the documentation using 2.6.3 in the meantime to avoid all those changes in source block of documentation, or choose a different Ruby parser in Yard. @JonRowe Your idea to compare version using a tools was a good suggestion. 😄 |
This is not an issue with Ripper. There is a change in Ruby 2.7
foo
# .bar
.baz #=> foo.baz That's why we have this kind of surprise. I will finish this first then probably try to look at yard if something can be done 🤷♂ |
Thanks @MSP-Greg. You were right, adding blank line fix #131 (comment) |
We are pretty ok. Some remaining noise in the diff but I inspect most of them without noticing any visual regressions. There is a change in Also in Next step will be to fix the comment visual issue in Yard, then change |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Thanks a lot for this enormous effort!
Looks good!
One confusing thing in diff:
defdef formattersformatters
@formatters@formatters
defdef reporterreporter
@reporter@reporter
defdef selfself..formattersformatters
@formatters@formatters ||=||= {{}}
is it just the differ's output?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Everything looks good.
Thanks a lot for this enormous effort!
If you're happy after diffing it @benoittgt 👍 |
Thanks! I will turn CI in green for all the PR against
Then I will merge and commit the change on master on each project. |
bundle exec rake "update_docs[3.9, enable-yard-and-bump-doc]"
fromrspec-dev
Yard update goes from lsegal/yard@v0.9.12...v0.9.24
To do
Index
There is a change in https://github.com/lsegal/yard/releases/tag/v0.9.19
This the page you get when you on the version number in documentation -> http://rspec.info/documentation/
At the moment we jump to https://github.com/rspec/rspec-rails/blob/master/README_DEV.md
Do we want to keep this behavior? With the last yard version we have
Do we want to change the index page?
README_DEV.md
seems pretty old but maybe we can update it.Doc version
This current version draft is incorrect because the branch used in each repo isupdate-travis-build-scripts-2020-01-01-for-master
. Andupdate-travis-build-scripts-2020-01-01-for-master
start from master not last release/maintenance branch.So I think the yard update should go on maintenance branch?Done:
Also the documentation rake task has been build to work on many repo at the same time. Soon
rspec-rails
will be released to 4. Should we split rake task forrspec-rails
, thenrspec-mocks
,rspec-core
,rspec-expectations
?At the moment this lead to rspec-rails doc published as 3.9 with beta features like ActionCable testing.