From 7ada54886818ecadbd74aded0e3c9d6d2e63bc94 Mon Sep 17 00:00:00 2001 From: Markus Reiter Date: Tue, 30 Mar 2021 04:38:45 +0200 Subject: [PATCH] Move YARD config into `Library/Homebrew`. --- .gitignore | 3 ++ .yardopts | 10 ----- Library/Homebrew/.yardopts | 12 ++++++ Library/Homebrew/README.md | 4 +- Library/Homebrew/sorbet/rbi/todo.rbi | 2 + Library/Homebrew/yard/ignore_directives.rb | 11 ++++++ .../default/docstring/html/internal.erb | 5 +++ .../default/docstring/html/private.erb | 5 +++ .../templates/default/docstring/html/setup.rb | 14 +++++++ .../default/module/html/item_summary.erb | 39 +++++++++++++++++++ 10 files changed, 93 insertions(+), 12 deletions(-) delete mode 100644 .yardopts create mode 100644 Library/Homebrew/.yardopts create mode 100644 Library/Homebrew/yard/ignore_directives.rb create mode 100644 Library/Homebrew/yard/templates/default/docstring/html/internal.erb create mode 100644 Library/Homebrew/yard/templates/default/docstring/html/private.erb create mode 100644 Library/Homebrew/yard/templates/default/docstring/html/setup.rb create mode 100644 Library/Homebrew/yard/templates/default/module/html/item_summary.erb diff --git a/.gitignore b/.gitignore index bdd631f909..82355a1044 100644 --- a/.gitignore +++ b/.gitignore @@ -32,6 +32,9 @@ **/vendor/bundle/ruby/*/gems/*/* **/vendor/bundle/ruby/*/specifications +# Ignore YARD files +**/.yardoc + # Unignore vendored gems !**/vendor/bundle/ruby/*/gems/*/lib !**/vendor/bundle/ruby/*/gems/rubocop-performance-*/config diff --git a/.yardopts b/.yardopts deleted file mode 100644 index 74d8880383..0000000000 --- a/.yardopts +++ /dev/null @@ -1,10 +0,0 @@ ---title "Homebrew" ---main Library/Homebrew/README.md ---markup markdown ---no-private ---exclude Library/Homebrew/test/ ---exclude Library/Homebrew/vendor/ ---exclude Library/Homebrew/compat/ -Library/Homebrew/**/*.rb -- -*.md diff --git a/Library/Homebrew/.yardopts b/Library/Homebrew/.yardopts new file mode 100644 index 0000000000..b9707ac3dc --- /dev/null +++ b/Library/Homebrew/.yardopts @@ -0,0 +1,12 @@ +--title "Homebrew Ruby API" +--main README.md +--markup markdown +--no-private +--load yard/ignore_directives.rb +--template-path yard/templates +--exclude test/ +--exclude vendor/ +--exclude compat/ +**/*.rb +- +*.md diff --git a/Library/Homebrew/README.md b/Library/Homebrew/README.md index 65f2cc1384..fb78ab260a 100644 --- a/Library/Homebrew/README.md +++ b/Library/Homebrew/README.md @@ -1,6 +1,6 @@ -# Homebrew's Formula API +# Homebrew Ruby API -This is the public API for Homebrew. +This is the public API for [Homebrew](https://github.com/Homebrew). The main class you should look at is the {Formula} class (and classes linked from there). That's the class that's used to create Homebrew formulae (i.e. package descriptions). Assume anything else you stumble upon is private. diff --git a/Library/Homebrew/sorbet/rbi/todo.rbi b/Library/Homebrew/sorbet/rbi/todo.rbi index ca35a66298..ecceecfa9d 100644 --- a/Library/Homebrew/sorbet/rbi/todo.rbi +++ b/Library/Homebrew/sorbet/rbi/todo.rbi @@ -3,6 +3,8 @@ # typed: strong module ::StackProf; end +module ::YARD::Docstring; end +module ::YARD::DocstringParser; end module DependencyCollector::Compat; end module GitHubPackages::JSONSchemer; end module OS::Mac::Version::NULL; end diff --git a/Library/Homebrew/yard/ignore_directives.rb b/Library/Homebrew/yard/ignore_directives.rb new file mode 100644 index 0000000000..4685ce026e --- /dev/null +++ b/Library/Homebrew/yard/ignore_directives.rb @@ -0,0 +1,11 @@ +# typed: false +# frozen_string_literal: true + +# from https://github.com/lsegal/yard/issues/484#issuecomment-442586899 +class IgnoreDirectiveDocstringParser < YARD::DocstringParser + def parse_content(content) + super(content&.sub(/(\A(typed|.*rubocop)|TODO):.*/m, "")) + end +end + +YARD::Docstring.default_parser = IgnoreDirectiveDocstringParser diff --git a/Library/Homebrew/yard/templates/default/docstring/html/internal.erb b/Library/Homebrew/yard/templates/default/docstring/html/internal.erb new file mode 100644 index 0000000000..569a4bf427 --- /dev/null +++ b/Library/Homebrew/yard/templates/default/docstring/html/internal.erb @@ -0,0 +1,5 @@ +

+ This <%= object.type %> is part of an internal API. + This <%= object.type %> may only be used internally in repositories owned by Homebrew, except in casks or formulae. + Third parties should avoid using this <%= object.type %> if possible, as it may be removed or be changed without warning. +

diff --git a/Library/Homebrew/yard/templates/default/docstring/html/private.erb b/Library/Homebrew/yard/templates/default/docstring/html/private.erb new file mode 100644 index 0000000000..e38e105dc5 --- /dev/null +++ b/Library/Homebrew/yard/templates/default/docstring/html/private.erb @@ -0,0 +1,5 @@ +

+ This <%= object.type %> is part of a private API. + This <%= object.type %> may only be used in the Homebrew/brew repository. + Third parties should avoid using this <%= object.type %> if possible, as it may be removed or be changed without warning. +

diff --git a/Library/Homebrew/yard/templates/default/docstring/html/setup.rb b/Library/Homebrew/yard/templates/default/docstring/html/setup.rb new file mode 100644 index 0000000000..6d07ea8198 --- /dev/null +++ b/Library/Homebrew/yard/templates/default/docstring/html/setup.rb @@ -0,0 +1,14 @@ +# typed: false +# frozen_string_literal: true + +def init + super + + return if sections.empty? + + sections[:index].place(:internal).before(:private) +end + +def internal + erb(:internal) if object.has_tag?(:api) && object.tag(:api).text == "internal" +end diff --git a/Library/Homebrew/yard/templates/default/module/html/item_summary.erb b/Library/Homebrew/yard/templates/default/module/html/item_summary.erb new file mode 100644 index 0000000000..bb3d573c24 --- /dev/null +++ b/Library/Homebrew/yard/templates/default/module/html/item_summary.erb @@ -0,0 +1,39 @@ + +
  • + + <% if @item.tags(:overload).size == 1 %> + <%= signature(@item.tag(:overload), true, false, !@item.attr_info) %> + <% else %> + <%= signature(@item, true, false, !@item.attr_info) %> + <% end %> + <% if @item.aliases.size > 0 %> + (also: <%= @item.aliases.map {|o| h(o.name(true)) }.join(", ") %>) + <% end %> + + <% if object != @item.namespace %> + + <%= @item.namespace.type == :class ? 'inherited' : (@item.scope == :class ? 'extended' : 'included') %> + from <%= linkify @item, object.relative_path(@item.namespace) %> + + <% end %> + <% if @item.constructor? %> + constructor + <% end %> + <% if rw = @item.attr_info %> + <% if !run_verifier([rw[:read]].compact).empty? && run_verifier([rw[:write]].compact).empty? %> + readonly + <% end %> + <% if !run_verifier([rw[:write]].compact).empty? && run_verifier([rw[:read]].compact).empty? %> + writeonly + <% end %> + <% end %> + <% if @item.visibility != :public %><%= @item.visibility %><% end %> + <% if @item.has_tag?(:abstract) %>abstract<% end %> + <% if @item.has_tag?(:deprecated) %>deprecated<% end %> + <% if @item.has_tag?(:api) && @item.tag(:api).text != 'public' %><%= @item.tag(:api).text %><% end %> + <% if @item.has_tag?(:deprecated) %> + Deprecated. <%= htmlify_line @item.tag(:deprecated).text %> + <% else %> + <%= htmlify_line docstring_summary(@item) %> + <% end %> +