Add rake command to generate yard documentation #2298
Conversation
|
Maybe we can wait for #2297 or don't forget to regenerate the doc after. |
2bc734c to
b6d6df9
Compare
b6d6df9 to
50c4086
Compare
Use it like: - `bundle exec rake "update_docs[4.0, 4-0-maintenance]"`
50c4086 to
5ed06ae
Compare
| cmd = "bundle install && \ | ||
| RUBYOPT='-I#{args[:website_path]}/lib' bundle exec yard \ | ||
| --yardopts .yardopts \ | ||
| --plugin rspec-docs-template \ |
There was a problem hiding this comment.
Is there any difference if we remove this option? I remember having some troubles installing this plugin.
There was a problem hiding this comment.
Yes. For example If I remove it. To install it. You have to go to https://github.com/rspec/rspec.github.io, source branche and install the gem manually. I will add some documentation about it.
--- a/source/documentation/4.0/rspec-rails/top-level-namespace.html
+++ b/source/documentation/4.0/rspec-rails/top-level-namespace.html
@@ -1,7 +1,8 @@
<!DOCTYPE html>
<html>
<head>
- <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+ <meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>
Top Level Namespace
@@ -9,11 +10,11 @@
</title>
- <link rel="stylesheet" href="/https/github.com/documentation/4.0/rspec-rails/css/style.css" type="text/css" charset="utf-8" />
+ <link rel="stylesheet" href="/https/github.com/documentation/4.0/rspec-rails/css/style.css" type="text/css" />
- <link rel="stylesheet" href="/https/github.com/documentation/4.0/rspec-rails/css/common.css" type="text/css" charset="utf-8" />
+ <link rel="stylesheet" href="/https/github.com/documentation/4.0/rspec-rails/css/common.css" type="text/css" />
- <link rel="stylesheet" href="/https/github.com/documentation/4.0/rspec-rails/css/rspec.css" type="text/css" charset="utf-8" />
+ <link rel="stylesheet" href="/https/github.com/documentation/4.0/rspec-rails/css/rspec.css" type="text/css" />
<script type="text/javascript">
pathId = "";
@@ -101,22 +102,11 @@
</div>
<div id="footer">
- Generated on Tue Mar 24 23:08:28 2020 by
+ Generated on Mon Mar 30 14:29:40 2020 by
<a href="http://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
0.9.24 (ruby-2.7.0).
</div>
-<script>
- (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
- (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
- m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
- })(window,document,'script','//www.google-analytics.com/analytics.js','ga');
-
- ga('create', 'UA-59095215-1', 'auto');
- ga('send', 'pageview');
-
-</script>
-There was a problem hiding this comment.
Honestly if those are the only changes we can ditch it, it was supposed to do what the ag command does now but I never made it workable.
There was a problem hiding this comment.
I'm debating wether we really want to do this at all, I mean it could still be managed from the rspec-dev tools with a bit of refactoring...
There was a problem hiding this comment.
As you. We can have command for rspec-rails documentation and another one for other project. I am not opposed to this proposal.
There was a problem hiding this comment.
I think I'd rather we have a task from the dev repo to do this, down the line maybe we can extract a common dependency
There was a problem hiding this comment.
Yard templates
I dig into a little bit, and the template does a bit more.
It choose different templates for the header and the footer.
Google Analytics
For example with this Google Analytics snippet rspec/rspec.github.io@7b9add7
Header properties
Also the header is a little bit different.
- <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+ <meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">We will use the default one from yard if we remove the plugin. How is better for mobile.
Do we want to keep Google Analytics? If no, I think there is no reason to keep this plugin anymore.
The diff without the plugin can be seen here https://github.com/rspec/rspec.github.io/compare/no-plugin-from-source?expand=1
It includes a little more changes because it pull each maintenance branch before generating the doc.
Shell commands
I added a command to remove empty lines... Ouch, there is so much...
rspec/rspec.github.io#139
All the PR are draft because I am waiting for your point of view. Especially for Google Analytics. :)
There was a problem hiding this comment.
If you want we can continue the discussion here. rspec/rspec-dev#245
There is already simple and double quote, the one liner is pretty complicated. Ruby do not have a clean way to write long string without carriage return + interpolation so we keep this one liner for the moment
|
This needs the white space trimming and a change to your already merged docs no? |
|
I was about to switch back to
|
We are now unsynced from other rspec gems versions so I moved (a little simpler version) of the rspec-dev function to the repo.
Use it like:
bundle exec rake "update_docs[4.0, 4-0-maintenance]"