Add --canonical-base-url cli option to docs generator (#5990)

* Add <link rel="canonical"> to the latest API docs * Revert "Add <link rel="canonical"> to the latest API docs" This reverts commit fc5068e. * Add --canonical-base-url cli option to docs generator * Generate crystal docs with --canonical-base-url set * Refactor HeadTemplate to DRY-it up a lil’
crystal-lang · Apr 25, 2018 · a6d0571 · a6d0571
1 parent 382d07e
commit a6d0571
Show file tree

Hide file tree

Showing 7 changed files with 29 additions and 18 deletions.
diff --git a/Makefile b/Makefile
@@ -92,7 +92,7 @@ compiler_spec: $(O)/compiler_spec ## Run compiler specs
 
 .PHONY: docs
 docs: ## Generate standard library documentation
-	$(BUILD_PATH) ./bin/crystal docs src/docs_main.cr
+	$(BUILD_PATH) ./bin/crystal docs -b https://crystal-lang.org/api/latest src/docs_main.cr
 
 .PHONY: crystal
 crystal: $(O)/crystal ## Build the compiler

diff --git a/src/compiler/crystal/command/docs.cr b/src/compiler/crystal/command/docs.cr
@@ -6,6 +6,7 @@
 class Crystal::Command
   private def docs
     output_directory = File.join(".", "docs")
+    canonical_base_url = nil
 
     OptionParser.parse(options) do |opts|
       opts.banner = <<-'BANNER'
@@ -20,6 +21,10 @@ class Crystal::Command
         output_directory = value
       end
 
+      opts.on("--canonical-base-url=URL", "-b URL", "Set the canonical base url") do |value|
+        canonical_base_url = value
+      end
+
       opts.on("-h", "--help", "Show this message") do
         puts opts
         exit
@@ -41,6 +46,6 @@ class Crystal::Command
     compiler.wants_doc = true
     result = compiler.top_level_semantic sources
 
-    Doc::Generator.new(result.program, included_dirs, output_directory).run
+    Doc::Generator.new(result.program, included_dirs, output_directory, canonical_base_url).run
   end
 end
diff --git a/src/compiler/crystal/tools/doc/generator.cr b/src/compiler/crystal/tools/doc/generator.cr
@@ -28,7 +28,7 @@ class Crystal::Doc::Generator
     },
   }
 
-  def initialize(@program : Program, @included_dirs : Array(String), @output_dir : String)
+  def initialize(@program : Program, @included_dirs : Array(String), @output_dir : String, @canonical_base_url : String?)
     @base_dir = Dir.current.chomp
     @types = {} of Crystal::Type => Doc::Type
     @repo_name = ""
@@ -74,7 +74,7 @@ class Crystal::Doc::Generator
       body = ""
     end
 
-    File.write File.join(@output_dir, "index.html"), MainTemplate.new(body, types, repository_name)
+    File.write File.join(@output_dir, "index.html"), MainTemplate.new(body, types, repository_name, @canonical_base_url)
 
     main_index = Main.new(raw_body, Type.new(self, @program), repository_name)
     File.write File.join(@output_dir, "index.json"), main_index
@@ -97,7 +97,7 @@ class Crystal::Doc::Generator
         filename = File.join(dir, "#{type.name}.html")
       end
 
-      File.write filename, TypeTemplate.new(type, all_types)
+      File.write filename, TypeTemplate.new(type, all_types, @canonical_base_url)
 
       next if type.program?
 

diff --git a/src/compiler/crystal/tools/doc/html/_head.html b/src/compiler/crystal/tools/doc/html/_head.html
@@ -1,6 +1,18 @@
-<meta charset="utf-8" />
+<meta charset="utf-8">
 <meta http-equiv="X-UA-Compatible" content="IE=edge">
 <meta name="generator" content="Crystal Docs <%= Crystal::VERSION %>">
 
-<link href="<%= base_path %>css/style.css" rel="stylesheet" type="text/css" />
+<%- if base_url = canonical_base_url -%>
+  <%- if path = type.try(&.path) -%>
+    <%- base_url = File.join(base_url, path) -%>
+  <%- end -%>
+  <link rel="canonical" href="<%= base_url %>">
+<% end -%>
+<%- base_path = type.try(&.path_to("")) -%>
+
+<link href="<%= base_path %>css/style.css" rel="stylesheet" type="text/css">
+
 <script type="text/javascript" src="<%= base_path %>js/doc.js"></script>
+<script type="text/javascript">
+  CrystalDoc.base_path = "<%= base_path %>";
+</script>
diff --git a/src/compiler/crystal/tools/doc/html/main.html b/src/compiler/crystal/tools/doc/html/main.html
@@ -1,12 +1,9 @@
 <!DOCTYPE html>
 <html lang="en">
 <head>
-  <%= HeadTemplate.new("") %>
+  <%= HeadTemplate.new(nil, canonical_base_url) %>
   <meta id="repository-name" content="<%= repository_name %>">
   <title>README - <%= repository_name %></title>
-  <script type="text/javascript">
-  CrystalDoc.base_path = "";
-  </script>
 </head>
 <body>
 

diff --git a/src/compiler/crystal/tools/doc/html/type.html b/src/compiler/crystal/tools/doc/html/type.html
@@ -1,12 +1,9 @@
 <!DOCTYPE html>
 <html lang="en">
 <head>
-  <%= HeadTemplate.new(type.path_to "") %>
+  <%= HeadTemplate.new(type, canonical_base_url) %>
   <meta id="repository-name" content="<%= type.repository_name %>">
   <title><%= type.full_name %> - <%= type.repository_name %></title>
-  <script type="text/javascript">
-    CrystalDoc.base_path = "<%= type.path_to "" %>";
-  </script>
 </head>
 <body>
 

diff --git a/src/compiler/crystal/tools/doc/templates.cr b/src/compiler/crystal/tools/doc/templates.cr
@@ -1,7 +1,7 @@
 require "ecr/macros"
 
 module Crystal::Doc
-  record TypeTemplate, type : Type, types : Array(Type) do
+  record TypeTemplate, type : Type, types : Array(Type), canonical_base_url : String? do
     ECR.def_to_s "#{__DIR__}/html/type.html"
   end
 
@@ -25,11 +25,11 @@ module Crystal::Doc
     ECR.def_to_s "#{__DIR__}/html/_other_types.html"
   end
 
-  record MainTemplate, body : String, types : Array(Type), repository_name : String do
+  record MainTemplate, body : String, types : Array(Type), repository_name : String, canonical_base_url : String? do
     ECR.def_to_s "#{__DIR__}/html/main.html"
   end
 
-  record HeadTemplate, base_path : String do
+  record HeadTemplate, type : Type?, canonical_base_url : String? do
     ECR.def_to_s "#{__DIR__}/html/_head.html"
   end