add better warning to prevent direct editing of auto-gen docs

activeadmin · Oct 23, 2013 · 2482f0e · 2482f0e
1 parent 26ab7a1
commit 2482f0e
Show file tree

Hide file tree

Showing 6 changed files with 31 additions and 9 deletions.
diff --git a/docs/3-index-pages/index-as-block.md b/docs/3-index-pages/index-as-block.md
@@ -1,4 +1,8 @@
-<!-- Please don't edit this file. It will be clobbered. -->
+<!--
+  WARNING: Please DO NOT edit this file! Update
+  source documentation in lib/active_admin/views
+  and execute rake yard to regenerate it.
+-->
 
 # Index as a Block
 

diff --git a/docs/3-index-pages/index-as-blog.md b/docs/3-index-pages/index-as-blog.md
@@ -1,4 +1,8 @@
-<!-- Please don't edit this file. It will be clobbered. -->
+<!--
+  WARNING: Please DO NOT edit this file! Update
+  source documentation in lib/active_admin/views
+  and execute rake yard to regenerate it.
+-->
 
 # Index as Blog
 

diff --git a/docs/3-index-pages/index-as-grid.md b/docs/3-index-pages/index-as-grid.md
@@ -1,4 +1,8 @@
-<!-- Please don't edit this file. It will be clobbered. -->
+<!--
+  WARNING: Please DO NOT edit this file! Update
+  source documentation in lib/active_admin/views
+  and execute rake yard to regenerate it.
+-->
 
 # Index as a Grid
 

diff --git a/docs/3-index-pages/index-as-table.md b/docs/3-index-pages/index-as-table.md
@@ -1,4 +1,8 @@
-<!-- Please don't edit this file. It will be clobbered. -->
+<!--
+  WARNING: Please DO NOT edit this file! Update
+  source documentation in lib/active_admin/views
+  and execute rake yard to regenerate it.
+-->
 
 # Index as a Table
 

diff --git a/tasks/docs.rake b/tasks/docs.rake
@@ -1,8 +1,13 @@
 namespace :docs do
 
-  def prepare_docstring(content)
-    "<!-- Please don't edit this file. It will be clobbered. -->\n\n#{content}\n"
-  end
+  AUTOGEN_WARNING = <<-EOD
+<!--
+  WARNING: Please DO NOT edit this file! Update
+  source documentation in lib/active_admin/views
+  and execute rake yard to regenerate it.
+-->
+
+EOD
 
   def filename_from_module(mod)
     mod.name.to_s.underscore.gsub('_', '-')
@@ -11,7 +16,7 @@ namespace :docs do
   def write_docstrings_to(path, mods)
     mods.each do |mod|
       File.open("#{path}/#{filename_from_module(mod)}.md", 'w+') do |f|
-        f << prepare_docstring(mod.docstring)
+        f << AUTOGEN_WARNING + mod.docstring + "\n"
       end
     end
   end

diff --git a/tasks/yard.rake b/tasks/yard.rake
@@ -2,5 +2,6 @@ require 'yard'
 require 'yard/rake/yardoc_task'
 
 YARD::Rake::YardocTask.new do |t|
-  t.files   = ['lib/**/*.rb']
+  t.after = ->{ Rake::Task['docs:build'].invoke }
+  t.files = ['lib/**/*.rb']
 end