From b7dbfe1b4d945a9f3c845f2929c460cb472ce794 Mon Sep 17 00:00:00 2001 From: Robin Dupret Date: Tue, 31 Jan 2017 21:33:50 +0100 Subject: Avoid documenting private or external classes There are a lot of monkey patches inside the code base but there's no need to document external constants so let's remove them from the documentation Also, since there are monkey patches for some test cases classes, there were sometimes both documented and sneaked under the wrong section in the sidebar. Finally, for future references, the `active_support/vendor` folder has been originally ignored in https://git.io/vDqfA but no longer exists. [ci skip] --- activesupport/lib/active_support/i18n_railtie.rb | 2 ++ activesupport/lib/active_support/xml_mini/libxml.rb | 2 ++ railties/lib/rails/api/task.rb | 9 ++++++--- railties/lib/rails/test_help.rb | 12 ++++++++---- 4 files changed, 18 insertions(+), 7 deletions(-) diff --git a/activesupport/lib/active_support/i18n_railtie.rb b/activesupport/lib/active_support/i18n_railtie.rb index b94368df14..b749913ee9 100644 --- a/activesupport/lib/active_support/i18n_railtie.rb +++ b/activesupport/lib/active_support/i18n_railtie.rb @@ -2,6 +2,8 @@ require "active_support" require "active_support/file_update_checker" require "active_support/core_ext/array/wrap" +# :enddoc: + module I18n class Railtie < Rails::Railtie config.i18n = ActiveSupport::OrderedOptions.new diff --git a/activesupport/lib/active_support/xml_mini/libxml.rb b/activesupport/lib/active_support/xml_mini/libxml.rb index 44b0bdb7dc..cde2967132 100644 --- a/activesupport/lib/active_support/xml_mini/libxml.rb +++ b/activesupport/lib/active_support/xml_mini/libxml.rb @@ -74,5 +74,7 @@ module LibXML #:nodoc: end end +# :enddoc: + LibXML::XML::Document.include(LibXML::Conversions::Document) LibXML::XML::Node.include(LibXML::Conversions::Node) diff --git a/railties/lib/rails/api/task.rb b/railties/lib/rails/api/task.rb index bc670b1d75..101e8806d0 100644 --- a/railties/lib/rails/api/task.rb +++ b/railties/lib/rails/api/task.rb @@ -8,8 +8,7 @@ module Rails include: %w( README.rdoc lib/active_support/**/*.rb - ), - exclude: "lib/active_support/vendor/*" + ) }, "activerecord" => { @@ -69,7 +68,11 @@ module Rails README.rdoc lib/**/*.rb ), - exclude: "lib/rails/generators/rails/**/templates/**/*.rb" + exclude: %w( + lib/rails/generators/rails/**/templates/**/*.rb + lib/rails/test_unit/* + lib/rails/api/generator.rb + ) } } diff --git a/railties/lib/rails/test_help.rb b/railties/lib/rails/test_help.rb index 5fda160012..0f9bf98737 100644 --- a/railties/lib/rails/test_help.rb +++ b/railties/lib/rails/test_help.rb @@ -14,10 +14,12 @@ require "active_support/testing/autorun" if defined?(ActiveRecord::Base) ActiveRecord::Migration.maintain_test_schema! - class ActiveSupport::TestCase - include ActiveRecord::TestFixtures - self.fixture_path = "#{Rails.root}/test/fixtures/" - self.file_fixture_path = fixture_path + "files" + module ActiveSupport + class TestCase + include ActiveRecord::TestFixtures + self.fixture_path = "#{Rails.root}/test/fixtures/" + self.file_fixture_path = fixture_path + "files" + end end ActionDispatch::IntegrationTest.fixture_path = ActiveSupport::TestCase.fixture_path @@ -27,6 +29,8 @@ if defined?(ActiveRecord::Base) end end +# :enddoc: + class ActionController::TestCase def before_setup # :nodoc: @routes = Rails.application.routes -- cgit v1.2.3 From 5be10c793650f98b69a13aa3d291b5e9b9fda3ea Mon Sep 17 00:00:00 2001 From: Robin Dupret Date: Tue, 31 Jan 2017 22:04:56 +0100 Subject: Properly nest core classes under a "Core Extensions" label Since Active Support is monkey patching a lot of core classes, let's rather document these changes under a new section so they are still documented but not encumbering the sidebar. We can safely remove the rescuing of the `LoadError` since as of cd7cc525, it's not possible to generate the API from an application. [ci skip] [Kasper Timm Hansen & Robin Dupret] --- railties/lib/rails/api/generator.rb | 28 ++++++++++++++++++++++++++++ railties/lib/rails/api/task.rb | 14 +++++--------- 2 files changed, 33 insertions(+), 9 deletions(-) create mode 100644 railties/lib/rails/api/generator.rb diff --git a/railties/lib/rails/api/generator.rb b/railties/lib/rails/api/generator.rb new file mode 100644 index 0000000000..dcc491783c --- /dev/null +++ b/railties/lib/rails/api/generator.rb @@ -0,0 +1,28 @@ +require "sdoc" + +class RDoc::Generator::API < RDoc::Generator::SDoc # :nodoc: + RDoc::RDoc.add_generator self + + def generate_class_tree_level(classes, visited = {}) + # Only process core extensions on the first visit. + if visited.empty? + core_exts, classes = classes.partition { |klass| core_extension?(klass) } + + super.unshift([ "Core extensions", "", "", build_core_ext_subtree(core_exts, visited) ]) + else + super + end + end + + private + def build_core_ext_subtree(classes, visited) + classes.map do |klass| + [ klass.name, klass.document_self_or_methods ? klass.path : "", "", + generate_class_tree_level(klass.classes_and_modules, visited) ] + end + end + + def core_extension?(klass) + klass.name != "ActiveSupport" && klass.in_files.any? { |file| file.absolute_name.include?("core_ext") } + end +end diff --git a/railties/lib/rails/api/task.rb b/railties/lib/rails/api/task.rb index 101e8806d0..d1f984be1d 100644 --- a/railties/lib/rails/api/task.rb +++ b/railties/lib/rails/api/task.rb @@ -1,4 +1,5 @@ require "rdoc/task" +require "rails/api/generator" module Rails module API @@ -83,7 +84,7 @@ module Rails # Be lazy computing stuff to have as light impact as possible to # the rest of tasks. before_running_rdoc do - load_and_configure_sdoc + configure_sdoc configure_rdoc_files setup_horo_variables end @@ -94,20 +95,15 @@ module Rails # no-op end - def load_and_configure_sdoc - require "sdoc" - + def configure_sdoc self.title = "Ruby on Rails API" self.rdoc_dir = api_dir options << "-m" << api_main options << "-e" << "UTF-8" - options << "-f" << "sdoc" + options << "-f" << "api" options << "-T" << "rails" - rescue LoadError - $stderr.puts %(Unable to load SDoc, please add\n\n gem 'sdoc', require: false\n\nto the Gemfile.) - exit 1 end def configure_rdoc_files @@ -150,7 +146,7 @@ module Rails end class RepoTask < Task - def load_and_configure_sdoc + def configure_sdoc super options << "-g" # link to GitHub, SDoc flag end -- cgit v1.2.3