From b626a9d5744bc7f90c513acbdd583d513bdc3ee2 Mon Sep 17 00:00:00 2001 From: Thibaut Courouble Date: Mon, 22 May 2017 17:13:07 -0400 Subject: [PATCH] Improve Erlang documentation Fixes #626. --- .../templates/pages/about_tmpl.coffee | 2 +- assets/javascripts/vendor/prism.js | 44 +++++++++++++++++++ assets/javascripts/views/pages/simple.coffee | 1 + assets/stylesheets/pages/_erlang.scss | 2 +- lib/docs/filters/erlang/clean_html.rb | 23 +++++----- lib/docs/filters/erlang/entries.rb | 12 +++-- lib/docs/scrapers/erlang.rb | 2 +- 7 files changed, 69 insertions(+), 17 deletions(-) diff --git a/assets/javascripts/templates/pages/about_tmpl.coffee b/assets/javascripts/templates/pages/about_tmpl.coffee index 51d5e679..d024f6ef 100644 --- a/assets/javascripts/templates/pages/about_tmpl.coffee +++ b/assets/javascripts/templates/pages/about_tmpl.coffee @@ -230,7 +230,7 @@ credits = [ 'https://raw.githubusercontent.com/elixir-lang/elixir/master/LICENSE' ], [ 'Erlang', - '1999-2016 Ericsson AB', + '2010-2017 Ericsson AB', 'Apache', 'https://raw.githubusercontent.com/erlang/otp/maint/LICENSE.txt' ], [ diff --git a/assets/javascripts/vendor/prism.js b/assets/javascripts/vendor/prism.js index 023b17a5..ee343658 100644 --- a/assets/javascripts/vendor/prism.js +++ b/assets/javascripts/vendor/prism.js @@ -1066,6 +1066,50 @@ Prism.languages.elixir.string.forEach(function(o) { }); +Prism.languages.erlang = { + 'comment': /%.+/, + 'string': { + pattern: /"(?:\\?.)*?"/, + greedy: true + }, + 'quoted-function': { + pattern: /'(?:\\.|[^'\\])+'(?=\()/, + alias: 'function' + }, + 'quoted-atom': { + pattern: /'(?:\\.|[^'\\])+'/, + alias: 'atom' + }, + 'boolean': /\b(?:true|false)\b/, + 'keyword': /\b(?:fun|when|case|of|end|if|receive|after|try|catch)\b/, + 'number': [ + /\$\\?./, + /\d+#[a-z0-9]+/i, + /(?:\b|-)\d*\.?\d+([Ee][+-]?\d+)?\b/ + ], + 'function': /\b[a-z][\w@]*(?=\()/, + 'variable': { + // Look-behind is used to prevent wrong highlighting of atoms containing "@" + pattern: /(^|[^@])(?:\b|\?)[A-Z_][\w@]*/, + lookbehind: true + }, + 'operator': [ + /[=\/<>:]=|=[:\/]=|\+\+?|--?|[=*\/!]|\b(?:bnot|div|rem|band|bor|bxor|bsl|bsr|not|and|or|xor|orelse|andalso)\b/, + { + // We don't want to match << + pattern: /(^|[^<])<(?!<)/, + lookbehind: true + }, + { + // We don't want to match >> + pattern: /(^|[^>])>(?!>)/, + lookbehind: true + } + ], + 'atom': /\b[a-z][\w@]*/, + 'punctuation': /[()[\]{}:;,.#|]|<<|>>/ + +}; Prism.languages.go = Prism.languages.extend('clike', { 'keyword': /\b(break|case|chan|const|continue|default|defer|else|fallthrough|for|func|go(to)?|if|import|interface|map|package|range|return|select|struct|switch|type|var)\b/, 'builtin': /\b(bool|byte|complex(64|128)|error|float(32|64)|rune|string|u?int(8|16|32|64|)|uintptr|append|cap|close|complex|copy|delete|imag|len|make|new|panic|print(ln)?|real|recover)\b/, diff --git a/assets/javascripts/views/pages/simple.coffee b/assets/javascripts/views/pages/simple.coffee index bb480508..91fd1c5c 100644 --- a/assets/javascripts/views/pages/simple.coffee +++ b/assets/javascripts/views/pages/simple.coffee @@ -24,6 +24,7 @@ app.views.DockerPage = app.views.DrupalPage = app.views.ElixirPage = app.views.EmberPage = +app.views.ErlangPage = app.views.ExpressPage = app.views.FlowPage = app.views.GoPage = diff --git a/assets/stylesheets/pages/_erlang.scss b/assets/stylesheets/pages/_erlang.scss index 259de7bb..ba221ec7 100644 --- a/assets/stylesheets/pages/_erlang.scss +++ b/assets/stylesheets/pages/_erlang.scss @@ -1,7 +1,7 @@ ._erlang { @extend %simple; - h3.code { @extend %code; } + h3 > code { display: block; } code.code { @extend %label; } .note { @extend %note; } .warning { @extend %note, %note-red; } diff --git a/lib/docs/filters/erlang/clean_html.rb b/lib/docs/filters/erlang/clean_html.rb index 2634e744..c30bc9d7 100644 --- a/lib/docs/filters/erlang/clean_html.rb +++ b/lib/docs/filters/erlang/clean_html.rb @@ -8,7 +8,7 @@ module Docs css('center:last-child').remove # copyright - css('center').each do |node| + css('center', '.example').each do |node| node.before(node.children).remove end @@ -30,12 +30,10 @@ module Docs # others - # css('p > br:last-child').remove - css('a[name]').each do |node| - parent = node.parent - parent = parent.parent while parent.name == 'span' - parent['id'] = node['name'] + # parent = node.parent + # parent = parent.parent while parent.name == 'span' + (node.next_element || node.parent)['id'] ||= node['name'] node.before(node.children).remove end @@ -48,10 +46,11 @@ module Docs css('p > .bold_code:first-child ~ br:last-child').each do |node| parent = node.parent parent.name = 'h3' - parent['class'] = 'code' - parent.css('*:not(a):not(br)').each { |n| n.before(n.children).remove } - node.remove - parent.inner_html = parent.inner_html.strip + parent.css('> br').remove + parent.css('> code').each do |code| + code.css('*:not(a):not(br)').each { |n| n.before(n.children).remove } + code.inner_html = code.inner_html.gsub('
', "\n").strip + end end css('pre:not(.REFTYPES) *:not(a)', 'a[href^=javascript]').each do |node| @@ -59,6 +58,7 @@ module Docs end css('pre:not(.REFTYPES)').each do |node| + node['data-language'] = 'erlang' node.inner_html = node.inner_html.strip_heredoc end @@ -80,6 +80,7 @@ module Docs node = node.next_element node.previous_element.remove end + html.gsub! %r{\n{2,}}, "\n" html.strip! html << "" node.before(html) @@ -98,6 +99,8 @@ module Docs node.remove_attribute('valign') end + css('.bold_code').remove_attr('class') + doc end end diff --git a/lib/docs/filters/erlang/entries.rb b/lib/docs/filters/erlang/entries.rb index 9ef50bd5..8f1ddcf1 100644 --- a/lib/docs/filters/erlang/entries.rb +++ b/lib/docs/filters/erlang/entries.rb @@ -42,12 +42,14 @@ module Docs return [] unless include_default_entry? if subpath.start_with?('lib/') - entry_nodes.map do |node| + names = Set.new + entry_nodes.each_with_object [] do |node, entries| id = node['name'] - name = id.gsub %r{\-(?.*)\z}, '/\k' + name = id.remove %r{\-\d*\z} + name << ' (type)' if name.sub!(/\Atype-/, '') name.remove! 'Module:' name.prepend "#{self.name}:" - [name, id] + entries << [name, id] if names.add?(name) end elsif subpath.start_with?('doc/') [] @@ -65,7 +67,9 @@ module Docs def entry_nodes @entry_nodes ||= if subpath.start_with?('lib/') - css('div.REFBODY + p > a') + css('p + div.REFBODY').each_with_object [] do |node, result| + result.concat(node.previous_element.css('a[name]').to_a) + end elsif subpath.start_with?('erts') link = at_css(".flipMenu a[href='#{File.basename(subpath, '.html')}']") list = link.parent.parent diff --git a/lib/docs/scrapers/erlang.rb b/lib/docs/scrapers/erlang.rb index 20cb0cdd..dfa4371a 100644 --- a/lib/docs/scrapers/erlang.rb +++ b/lib/docs/scrapers/erlang.rb @@ -36,7 +36,7 @@ module Docs ] options[:attribution] = <<-HTML - © 1999–2016 Ericsson AB
+ © 2010–2017 Ericsson AB
Licensed under the Apache License, Version 2.0. HTML