Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

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

Merged
merged 5 commits into from
Apr 25, 2018
Merged

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

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
fc5068e
Add <link rel="canonical"> to the latest API docs
Sija Apr 22, 2018
cdd498b
Revert "Add <link rel="canonical"> to the latest API docs"
Sija Apr 22, 2018
7054658
Add --canonical-base-url cli option to docs generator
Sija Apr 23, 2018
b4954d7
Generate crystal docs with --canonical-base-url set
Sija Apr 23, 2018
309bc4a
Refactor HeadTemplate to DRY-it up a lil’
Sija Apr 23, 2018
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion Makefile
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
7 changes: 6 additions & 1 deletion src/compiler/crystal/command/docs.cr
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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'
Expand All @@ -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
Expand All @@ -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
6 changes: 3 additions & 3 deletions src/compiler/crystal/tools/doc/generator.cr
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 = ""
Expand Down Expand Up @@ -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
Expand All @@ -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?

Expand Down
16 changes: 14 additions & 2 deletions src/compiler/crystal/tools/doc/html/_head.html
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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>
5 changes: 1 addition & 4 deletions src/compiler/crystal/tools/doc/html/main.html
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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>

Expand Down
5 changes: 1 addition & 4 deletions src/compiler/crystal/tools/doc/html/type.html
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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>

Expand Down
6 changes: 3 additions & 3 deletions src/compiler/crystal/tools/doc/templates.cr
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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

Expand All @@ -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

Expand Down