From fc5068e7937800f9fa2ebc1e938d4b8329b5f7f9 Mon Sep 17 00:00:00 2001 From: Sijawusz Pur Rahnama Date: Sun, 22 Apr 2018 20:41:33 +0200 Subject: [PATCH 1/5] Add to the latest API docs --- src/compiler/crystal/tools/doc/html/main.html | 5 ++++- src/compiler/crystal/tools/doc/html/type.html | 3 +++ src/compiler/crystal/tools/doc/main.cr | 3 +++ 3 files changed, 10 insertions(+), 1 deletion(-) diff --git a/src/compiler/crystal/tools/doc/html/main.html b/src/compiler/crystal/tools/doc/html/main.html index 852e89799a2e..650bc691a3e4 100644 --- a/src/compiler/crystal/tools/doc/html/main.html +++ b/src/compiler/crystal/tools/doc/html/main.html @@ -5,8 +5,11 @@ README - <%= repository_name %> + <% if repository_name == CRYSTAL_REPOSITORY_NAME %> + + <% end %> diff --git a/src/compiler/crystal/tools/doc/html/type.html b/src/compiler/crystal/tools/doc/html/type.html index b05fd0ab9a2d..8f045e3b7f1c 100644 --- a/src/compiler/crystal/tools/doc/html/type.html +++ b/src/compiler/crystal/tools/doc/html/type.html @@ -7,6 +7,9 @@ + <% if type.repository_name == CRYSTAL_REPOSITORY_NAME %> + " /> + <% end %> diff --git a/src/compiler/crystal/tools/doc/main.cr b/src/compiler/crystal/tools/doc/main.cr index 0f3c5e12d60e..4673e7806138 100644 --- a/src/compiler/crystal/tools/doc/main.cr +++ b/src/compiler/crystal/tools/doc/main.cr @@ -1,4 +1,7 @@ module Crystal::Doc + CRYSTAL_REPOSITORY_NAME = "github.com/crystal-lang/crystal" + CANONICAL_BASE_URL = "https://crystal-lang.org/api/latest" + record Main, body : String, program : Type, repository_name : String do def to_s(io : IO) to_json(io) From cdd498b3e685c87eafc5f31339858238d4925e2b Mon Sep 17 00:00:00 2001 From: Sijawusz Pur Rahnama Date: Sun, 22 Apr 2018 22:20:08 +0200 Subject: [PATCH 2/5] Revert "Add to the latest API docs" This reverts commit fc5068e7937800f9fa2ebc1e938d4b8329b5f7f9. --- src/compiler/crystal/tools/doc/html/main.html | 5 +---- src/compiler/crystal/tools/doc/html/type.html | 3 --- src/compiler/crystal/tools/doc/main.cr | 3 --- 3 files changed, 1 insertion(+), 10 deletions(-) diff --git a/src/compiler/crystal/tools/doc/html/main.html b/src/compiler/crystal/tools/doc/html/main.html index 650bc691a3e4..852e89799a2e 100644 --- a/src/compiler/crystal/tools/doc/html/main.html +++ b/src/compiler/crystal/tools/doc/html/main.html @@ -5,11 +5,8 @@ README - <%= repository_name %> - <% if repository_name == CRYSTAL_REPOSITORY_NAME %> - - <% end %> diff --git a/src/compiler/crystal/tools/doc/html/type.html b/src/compiler/crystal/tools/doc/html/type.html index 8f045e3b7f1c..b05fd0ab9a2d 100644 --- a/src/compiler/crystal/tools/doc/html/type.html +++ b/src/compiler/crystal/tools/doc/html/type.html @@ -7,9 +7,6 @@ - <% if type.repository_name == CRYSTAL_REPOSITORY_NAME %> - " /> - <% end %> diff --git a/src/compiler/crystal/tools/doc/main.cr b/src/compiler/crystal/tools/doc/main.cr index 4673e7806138..0f3c5e12d60e 100644 --- a/src/compiler/crystal/tools/doc/main.cr +++ b/src/compiler/crystal/tools/doc/main.cr @@ -1,7 +1,4 @@ module Crystal::Doc - CRYSTAL_REPOSITORY_NAME = "github.com/crystal-lang/crystal" - CANONICAL_BASE_URL = "https://crystal-lang.org/api/latest" - record Main, body : String, program : Type, repository_name : String do def to_s(io : IO) to_json(io) From 7054658347e06394c97454a2bbbdde1a574cc94e Mon Sep 17 00:00:00 2001 From: Sijawusz Pur Rahnama Date: Mon, 23 Apr 2018 02:08:21 +0200 Subject: [PATCH 3/5] Add --canonical-base-url cli option to docs generator --- src/compiler/crystal/command/docs.cr | 7 ++++++- src/compiler/crystal/tools/doc/generator.cr | 6 +++--- src/compiler/crystal/tools/doc/html/main.html | 5 ++++- src/compiler/crystal/tools/doc/html/type.html | 3 +++ src/compiler/crystal/tools/doc/templates.cr | 4 ++-- 5 files changed, 18 insertions(+), 7 deletions(-) diff --git a/src/compiler/crystal/command/docs.cr b/src/compiler/crystal/command/docs.cr index 1ccd0b868a2f..d93e03e7d336 100644 --- 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 index 42faae2e5edc..ae94e6a2a2d9 100644 --- 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/main.html b/src/compiler/crystal/tools/doc/html/main.html index 852e89799a2e..a4837ecdeada 100644 --- a/src/compiler/crystal/tools/doc/html/main.html +++ b/src/compiler/crystal/tools/doc/html/main.html @@ -5,8 +5,11 @@ README - <%= repository_name %> + <% if canonical_base_url %> + + <% end %> diff --git a/src/compiler/crystal/tools/doc/html/type.html b/src/compiler/crystal/tools/doc/html/type.html index b05fd0ab9a2d..060b9fd454fd 100644 --- a/src/compiler/crystal/tools/doc/html/type.html +++ b/src/compiler/crystal/tools/doc/html/type.html @@ -7,6 +7,9 @@ + <% if base_url = canonical_base_url %> + + <% end %> diff --git a/src/compiler/crystal/tools/doc/templates.cr b/src/compiler/crystal/tools/doc/templates.cr index 2e7390288075..c1269cb0d8fa 100644 --- 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,7 +25,7 @@ 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 From b4954d7c2483ef259d02927f7a0fb9f0e54e8440 Mon Sep 17 00:00:00 2001 From: Sijawusz Pur Rahnama Date: Mon, 23 Apr 2018 02:08:59 +0200 Subject: [PATCH 4/5] Generate crystal docs with --canonical-base-url set --- Makefile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Makefile b/Makefile index 6fdaaff69f97..63a96877e3d8 100644 --- 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 From 309bc4a7215a35ff3798c560f57831f1058b7bce Mon Sep 17 00:00:00 2001 From: Sijawusz Pur Rahnama Date: Mon, 23 Apr 2018 14:14:46 +0200 Subject: [PATCH 5/5] =?UTF-8?q?Refactor=20HeadTemplate=20to=20DRY-it=20up?= =?UTF-8?q?=20a=20lil=E2=80=99?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- src/compiler/crystal/tools/doc/html/_head.html | 16 ++++++++++++++-- src/compiler/crystal/tools/doc/html/main.html | 8 +------- src/compiler/crystal/tools/doc/html/type.html | 8 +------- src/compiler/crystal/tools/doc/templates.cr | 2 +- 4 files changed, 17 insertions(+), 17 deletions(-) diff --git a/src/compiler/crystal/tools/doc/html/_head.html b/src/compiler/crystal/tools/doc/html/_head.html index d95c11ee7ecb..b670712dd6f6 100644 --- a/src/compiler/crystal/tools/doc/html/_head.html +++ b/src/compiler/crystal/tools/doc/html/_head.html @@ -1,6 +1,18 @@ - + - +<%- if base_url = canonical_base_url -%> + <%- if path = type.try(&.path) -%> + <%- base_url = File.join(base_url, path) -%> + <%- end -%> + +<% end -%> +<%- base_path = type.try(&.path_to("")) -%> + + + + diff --git a/src/compiler/crystal/tools/doc/html/main.html b/src/compiler/crystal/tools/doc/html/main.html index a4837ecdeada..2c6e42152d6d 100644 --- a/src/compiler/crystal/tools/doc/html/main.html +++ b/src/compiler/crystal/tools/doc/html/main.html @@ -1,15 +1,9 @@ - <%= HeadTemplate.new("") %> + <%= HeadTemplate.new(nil, canonical_base_url) %> README - <%= repository_name %> - - <% if canonical_base_url %> - - <% end %> diff --git a/src/compiler/crystal/tools/doc/html/type.html b/src/compiler/crystal/tools/doc/html/type.html index 060b9fd454fd..d01860200e3b 100644 --- a/src/compiler/crystal/tools/doc/html/type.html +++ b/src/compiler/crystal/tools/doc/html/type.html @@ -1,15 +1,9 @@ - <%= HeadTemplate.new(type.path_to "") %> + <%= HeadTemplate.new(type, canonical_base_url) %> <%= type.full_name %> - <%= type.repository_name %> - - <% if base_url = canonical_base_url %> - - <% end %> diff --git a/src/compiler/crystal/tools/doc/templates.cr b/src/compiler/crystal/tools/doc/templates.cr index c1269cb0d8fa..e55e7d225153 100644 --- a/src/compiler/crystal/tools/doc/templates.cr +++ b/src/compiler/crystal/tools/doc/templates.cr @@ -29,7 +29,7 @@ module Crystal::Doc 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