refactors and fixes in guides generation [ci skip]

This commit is not precisely atomic, but the changes have evolved, summary:

* The ENV-based interface has been moved upwards, the generator has now a conventional
  initializer.

* RAILS_VERSION is now assumed to be a Git tag. A blank RAILS_VERSION means edge guides.

* In consequence, the EDGE env variable is gone.

* The "local" version is also gone, the current SHA1 is computed for edge guides.

* Assumes guides are generated from a repo checkout (time ago users could
  generate them from gems.)

* The WARNINGS flag is gone in consequence, you cannot disable warnings.

* The `api_link` Markdown helper is fixed.

* Docs about usage have one single place: rake guides:help.

* Links in guides have been revised.

1 files changed, 9 insertions, 13 deletions

diff --git a/guides/Rakefile b/guides/Rakefile
index d2591f523c..ccb42f3273 100644
--- a/guides/Rakefile
+++ b/guides/Rakefile
@@ -1,10 +1,8 @@
 namespace :guides do
-
   desc 'Generate guides (for authors), use ONLY=foo to process just "foo.md"'
   task generate: "generate:html"
 
   namespace :generate do
-
     desc "Generate HTML guides"
     task :html do
       ENV["WARNINGS"] = "1" # authors can't disable this
@@ -18,7 +16,7 @@ namespace :guides do
         abort "Please run `setupkindlerb` to install kindlegen"
       end
       unless `convert` =~ /convert/
-        abort "Please install ImageMagick`"
+        abort "Please install ImageMagick"
       end
       ENV["KINDLE"] = "1"
       Rake::Task["guides:generate:html"].invoke
@@ -33,7 +31,7 @@ namespace :guides do
 
   desc "Show help"
   task :help do
-    puts <<-help
+    puts <<HELP
 
 Guides are taken from the source directory, and the result goes into the
 output directory. Assets are stored under files, and copied to output/files as
@@ -46,8 +44,9 @@ All of these processes are handled via rake tasks, here's a full list of them:
 #{%x[rake -T]}
 Some arguments may be passed via environment variables:
 
-  WARNINGS=1
-    Internal links (anchors) are checked, also detects duplicated IDs.
+  RAILS_VERSION=tag
+    If guides are being generated for a specific Rails version set the Git tag
+    here, otherwise the current SHA1 is going to be used to generate edge guides.
 
   ALL=1
     Force generation of all guides.
@@ -65,15 +64,12 @@ Some arguments may be passed via environment variables:
     Use it when you want to generate translated guides in
     source/<GUIDES_LANGUAGE> folder (such as source/es)
 
-  EDGE=1
-    Indicate generated guides should be marked as edge.
-
 Examples:
-  $ rake guides:generate ALL=1
-  $ rake guides:generate EDGE=1
-  $ rake guides:generate:kindle EDGE=1
+  $ rake guides:generate ALL=1 RAILS_VERSION=v5.1.0
+  $ rake guides:generate ONLY=migrations
+  $ rake guides:generate:kindle
   $ rake guides:generate GUIDES_LANGUAGE=es
-    help
+HELP
   end
 end