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

Update doc with updated yard #131

Merged
merged 6 commits into from
Mar 8, 2020
Merged

Update doc with updated yard #131

merged 6 commits into from
Mar 8, 2020

Conversation

benoittgt
Copy link
Member

@benoittgt benoittgt commented Jan 2, 2020

bundle exec rake "update_docs[3.9, enable-yard-and-bump-doc]" from rspec-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

Fixed parsing order of README files. YARD will now prefer README over
README.md over README.x.md or README-x.md (and the like). READMEs will now
also be ordered by filename; the first README is still chosen unless
--readme is provided.

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

Capture d’écran 2020-01-02 à 14 32 44

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 is update-travis-build-scripts-2020-01-01-for-master. And update-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 for rspec-rails, then rspec-mocks, rspec-core, rspec-expectations?
At the moment this lead to rspec-rails doc published as 3.9 with beta features like ActionCable testing.

@benoittgt
Copy link
Member Author

benoittgt commented Jan 2, 2020

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
@benoittgt benoittgt force-pushed the re-enable-yard-check branch from 8a499e3 to b5d6c5d Compare January 2, 2020 15:35
@benoittgt
Copy link
Member Author

Initial PR has been updated with new rake command. The doc is now generated using 3-9-maintenance branchs + yard update.

@benoittgt benoittgt marked this pull request as ready for review January 2, 2020 15:40
@benoittgt benoittgt changed the title Run rspec-dev commands on update script branch Update doc with updated yard Jan 2, 2020
@JonRowe
Copy link
Member

JonRowe commented Jan 4, 2020

@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 https://percy.io/visual-testing on them to check for changes on any pages against master?

@benoittgt
Copy link
Member Author

benoittgt commented Jan 5, 2020

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 😅:

Capture d’écran 2020-01-05 à 18 25 17

EDIT: Source of the local build https://percy.io/RSpec/rspec.github.io/builds/3633498

@benoittgt
Copy link
Member Author

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:

Do we want to change the index page? README_DEV.md seems pretty old but maybe we can update it.

@benoittgt
Copy link
Member Author

I will try to do it before this week-end to close all related PR.

@JonRowe
Copy link
Member

JonRowe commented Jan 9, 2020

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

@benoittgt
Copy link
Member Author

benoittgt commented Jan 16, 2020

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:

  • Assertions moved:

Capture d’écran 2020-01-16 à 15 28 08

- File list

Capture d’écran 2020-01-16 à 20 30 00

- Summary signatures ("object" is in a different position). I still need to improve this noisy change.

Capture d’écran 2020-01-16 à 20 31 36

I also disable all "collapse", they change from (collapse) to {collapse}. We still ends up with a diff with some work:

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 😊

@JonRowe
Copy link
Member

JonRowe commented Jan 18, 2020

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

@benoittgt
Copy link
Member Author

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

Capture d’écran 2020-01-24 à 15 12 03

At the end of doc you can get details.

Capture d’écran 2020-01-24 à 15 12 18

@benoittgt
Copy link
Member Author

I will switch the script to check all the page of current yard and will inspect diff. 😱

@JonRowe
Copy link
Member

JonRowe commented Jan 24, 2020

Are you sure they're just not collapsed?
Screen Shot 2020-01-24 at 20 01 17

@benoittgt
Copy link
Member Author

You are completely right Jon. Sorry.

@JonRowe
Copy link
Member

JonRowe commented Jan 27, 2020

No need to apologise, thank you for looking at this!

@benoittgt
Copy link
Member Author

benoittgt commented Jan 28, 2020

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

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 traverse from Nokogiri to go threw all children but in that case it means I will check the old website node for RSpec multiple times ("const" class, "object_link" sub class, "a" link, text content).

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.

@benoittgt
Copy link
Member Author

benoittgt commented Jan 28, 2020

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
I made a hacky script for that.

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:

  • Change yard command to do not alter index link

@benoittgt
Copy link
Member Author

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.

@JonRowe
Copy link
Member

JonRowe commented Jan 29, 2020

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]"
```
@benoittgt
Copy link
Member Author

benoittgt commented Jan 29, 2020

There is something weird from yard or maybe from us.
We have this code

#... separate custom file using the --options command-line parameter.

yard v0.9.12 VS yard v0.9.22
Capture d’écran 2020-01-29 à 16 40 58

Yard display –options instead of --options.

It is not happening everywhere.
Capture d’écran 2020-01-29 à 16 54 24

This should normally not happen because we have in .yardopts

 	--markup markdown
	--markup-provider redcarpet

and we have also another .yardopts in each project but also with --markup markdown
https://github.com/rspec/rspec-core/blob/enable-yard-and-bump-doc/.yardopts


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
/* .yardopts */
--markup markdown

Capture d’écran 2020-01-29 à 18 51 34

Without --markup opts:

Capture d’écran 2020-01-29 à 18 56 14

@benoittgt
Copy link
Member Author

benoittgt commented Jan 29, 2020

Also with the code:

      def reporter
	        # @reporter_buffer should only ever be set in this method to cover
	        # initialization of @reporter.

yard v0.9.12 VS yard v0.9.22
Capture d’écran 2020-01-29 à 17 05 56

First comment line have carriage return removed.

@benoittgt
Copy link
Member Author

benoittgt commented Jan 29, 2020

There is a big removal of the comment from RSpec::Core::Formatters

yard v0.9.12 VS yard v0.9.22
Capture d’écran 2020-01-29 à 17 16 12

It seems to be linked to lsegal/yard#1173 but I do not understand why it is not working anymore. 🤔

@benoittgt
Copy link
Member Author

benoittgt commented Jan 29, 2020

Again "Overview" rely on a different part.

Code : https://github.com/rspec/rspec-rails/blob/a60adc94694177ca8cf3d126f6684c579e83307e/lib/rspec/rails/example/mailer_example_group.rb#L1-L16

yard v0.9.12 VS yard v0.9.22
Capture d’écran 2020-01-29 à 17 54 10

It seems a similar issue to #131 (comment)

@benoittgt
Copy link
Member Author

@lsegal by any chance do you have ideas for the last 4 comments?

Thanks

@benoittgt
Copy link
Member Author

For #131 (comment) and the weird --X formatting. RedCarpet was not properly installed in repos. I did a bundle exec rake run["bundle update redcarpet"] from rspec-dev and it fix the issue.

Capture d’écran 2020-02-26 à 15 33 19

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"]`
@MSP-Greg
Copy link

MSP-Greg commented Mar 4, 2020

@benoittgt

Saw your issue in YARD, and ended up here. The problem above with RSpec::Core::Formatters can be solved by adding a blank line below the first line:

RSpec::Support.require_rspec_support "directory_maker"

Really, the comment for the RSpec::Core::Formatters module needs a blank line above it. I've only seen this with module/class comments, not method or constant comments.

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...

@benoittgt
Copy link
Member Author

benoittgt commented Mar 4, 2020

Thank you very much @MSP-Greg. I tried to add one line on RSpec::Support.require_rspec_support "directory_maker"

--- 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:
http://rspec.info/documentation/3.9/rspec-core/RSpec/Core/Configuration.html#reporter-instance_method

Who is different.

I am gonna look at Ripper.

@MSP-Greg
Copy link

MSP-Greg commented Mar 4, 2020

@benoittgt

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 RSpec::Core::Configuration#reporter, I'm not seeing that with YARD 0.9.20, at least not at https://msp-greg.github.io/rspec/RSpec/Core/Configuration.html#reporter-instance_method.

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...

@benoittgt
Copy link
Member Author

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

@benoittgt
Copy link
Member Author

benoittgt commented Mar 6, 2020

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. 😄

@benoittgt
Copy link
Member Author

benoittgt commented Mar 6, 2020

This is not an issue with Ripper. There is a change in Ruby 2.7

Comment lines can be placed between fluent dot now. source

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 🤷‍♂

@benoittgt
Copy link
Member Author

Thanks @MSP-Greg. You were right, adding blank line fix #131 (comment)

@benoittgt
Copy link
Member Author

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 documentation/3.9/rspec-core/RSpec/Core/Formatters.html because I added a blank line to avoid hiding big block of comment/documentation at the beginning of the file.
See: rspec/rspec-core@90af053

Also in documentation/3.9/rspec-rails/RSpec/Rails/MailerExampleGroup.html I agree with the change form Yard. The previous documentation we had was if ActionMailer was not defined.


Next step will be to fix the comment visual issue in Yard, then change rspec-dev rake command to deal with rspec-rails 4 documentation.

@benoittgt benoittgt requested review from JonRowe and pirj March 6, 2020 14:17
Copy link
Member

@pirj pirj left a 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?

Copy link
Member

@pirj pirj left a 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!

@benoittgt
Copy link
Member Author

is it just the differ's output?

Yes it is :)

Capture d’écran 2020-03-07 à 21 28 23

Thanks for the review.

@JonRowe
Copy link
Member

JonRowe commented Mar 7, 2020

If you're happy after diffing it @benoittgt 👍

@benoittgt
Copy link
Member Author

benoittgt commented Mar 8, 2020

Thanks!

I will turn CI in green for all the PR against 3-9-maintenance:

Then I will merge and commit the change on master on each project.

@benoittgt benoittgt merged commit b6c2e3d into source Mar 8, 2020
@benoittgt benoittgt deleted the re-enable-yard-check branch March 8, 2020 17:11
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.

4 participants