Regenerate doc with recent yard to avoid visual issue in "Inherits"

[benoittgt]

Fix: #148

I used from rspec-dev : bundle exec rake "update_docs[3.8, 3-8-maintenance]"

We jump related dependencies too (rdoc for example because we use a different Ruby version).

An example of a yard footer to see the bump in versions.

-    <div id="footer">
-  Generated on Fri Sep 14 00:02:14 2018 by
+
+      <div id="footer">
+  Generated on Tue Jul 28 15:19:27 2020 by
   <a href="http://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
-  0.8.7.6 (ruby-2.5.1).
+  0.9.25 (ruby-2.7.1).

Side note. I noticed that the footer was not fully visible on Firefox. lsegal/yard#1346

[pirj]

3.8 is fine, but in 3.7 and down are still broken.
What I've noticed that initially it loads just fine, and then a screen update happens and it appears broken. JS?

Also, it seems that for pre-3.8 the left panel went missing

[JonRowe]

3.8 is fine, but in 3.7 and down are still broken.
What I've noticed that initially it loads just fine, and then a screen update happens and it appears broken. JS?

Also, it seems that for pre-3.8 the left panel went missing

Given that this PR only affects 3.8...

[JonRowe]

This diff is too big to verify, @benoittgt if you're happy these changes are beneficial go ahead and merge

[pirj]

Sorry, missed that it's only for 3.8.
No plans to fix earlier versions? I guess we can only glance over and hope it's ok anyway.

[JonRowe]

No plans to fix earlier versions?

If you, or anyone else wishes to put the time in to update them, I'm happy for that to happen, the problem is that we simply can't verify the docs are identical, so we've typical gone with "what worked at the time" and crossed fingers.

[JonRowe]

In an ideal world... there would be a source code repo that simply generated docs and verified the output, and we wouldn't inspect the result of that pipeline, just update yard and rerun on all versions, but we don't have that 😂

[benoittgt]

tl;dr : How many gem versions we want to maintain?

---

The issue is there is a lot of change in rdoc or yard. So CSS/HTML can be altered a lot and with the amount of doc we have it is complicated to track, even with visual tool like Percy.

I ran Percy for this PR but only on rspec-core to avoid having to many screenshots to compare: https://percy.io/RSpec/rspec.github.io/builds/6292116

With the visual diff we can see that now bulleted list have a different space between items. So it means that every time we have list, the visual diff turns into a mess for the rest of the web page. :)

If we use webpage text content diff we will still have surprise because html structure can change over time.

For example we can see again that we need to backport rspec/rspec-core@5de10ff to 3.8 if we want to keep the doc of rspec-core's formatter fully visible...

If we want to fix the visual glitch (#148) on versions < 3.9 we need to:

1. Bump yard
2. See if we need to bump Ruby too
3. Backport commits that are necessary for a good documentation like rspec/rspec-core@5de10ff to all previous versions...
4. Release a new version of the gem (so it means that yard version bump should be linked to the content of our release, because we will not make release only for documentation formatting).
5. Inspect using visual diff or webpage text content diff
6. Make the review
7. 🤯

We should set a limit of version we maintain for documentation (same as Ruby version) because this lead to too much work. When I watch this numbered list, it makes documentation like a mandatory patch version for our gems and it is probably not the path we want to take. 😄

Sorry for this out of thread comment. Thanks for you reviews. With all of what I said, I am not sure we want to merge this PR. 😕

[pirj]

Thanks for this comprehensive explanation. You are more than right, @benoittgt.

With all this in mind, I vote to support only the current version.
If the current version docs are broken - we fix it. When we release a new version, docs for all previous are set in stone.
Don't see a big problem with that - 3.8 was around for a long while, nobody complained and we didn't notice any discrepancies.

Thank you for making an extra mile with fixing the previous version. It was my mistake to file #148 in the first place.

[benoittgt]

Thank you for making an extra mile with fixing the previous version. It was my mistake to file #148 in the first place.

No no, it was a good thing. We just need to clarify how much we want to maintain gem version. I should have ask earlier. :)

[JonRowe]

We should go to best efforts maintain the current version docs, but we don't have the bandwidth to re-generate old docs., that said if someone does do it then it's ok to merge them within reason.

I'm happy with this if you want to merge it @benoittgt