From b7dbfe1b4d945a9f3c845f2929c460cb472ce794 Mon Sep 17 00:00:00 2001
From: Robin Dupret <robin.dupret@gmail.com>
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]
---
 railties/lib/rails/api/task.rb | 9 ++++++---
 1 file changed, 6 insertions(+), 3 deletions(-)

(limited to 'railties/lib/rails/api')

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
+          )
         }
       }
 
-- 
cgit v1.2.3


From 5be10c793650f98b69a13aa3d291b5e9b9fda3ea Mon Sep 17 00:00:00 2001
From: Robin Dupret <robin.dupret@gmail.com>
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

(limited to 'railties/lib/rails/api')

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