From cd7cc5254b090ccbb84dcee4408a5acede25ef2a Mon Sep 17 00:00:00 2001 From: Xavier Noria Date: Fri, 6 Feb 2015 20:06:29 +0100 Subject: Remove documentation tasks This patch removes the tasks doc:app, doc:rails, and doc:guides. In our experience applications do not generate APIs using doc:app. Methods may be certainly documented for maintainers, annotated with YARD tags, etc. but that is intended to be read with the source code, not in a separate website. Then, teams also have typically selected topics written down in Markdown files, or in a GitHub wiki... that kind of thing. If a team absolutely needs to generate application documentation for internal purposes, they can still easily write their own task. Regarding doc:rails and doc:guides, we live in 2015. We are used to go to online docs all the time. If you really want access to the API offline RubyGems generates it for every Rails component unless you tell it not to, and you can checkout the Rails source code to read the guides as Markdown, or download them for a Kindle reader. All in all, maintaining this code does not seem to be worthwhile anymore. As a consequence of this, guides (+3 MB uncompressed) won't be distributed with the rails gem anymore. Of course, guides and API are going to be still part of releases, since documentation is maintained alongside code and tests. Also, time permitting, this will allow us to experiment with novel ways to generate documentation in the Rails docs server, since right now we were constrained by being able to generate them in the user's environment. --- guides/source/command_line.md | 8 --- guides/source/getting_started.md | 13 ---- rails.gemspec | 2 +- railties/CHANGELOG.md | 4 ++ railties/lib/rails/api/task.rb | 14 ----- railties/lib/rails/generators/app_base.rb | 6 -- .../generators/rails/app/templates/README.rdoc | 4 -- railties/lib/rails/tasks/documentation.rake | 70 ---------------------- railties/test/generators/app_generator_test.rb | 5 -- 9 files changed, 5 insertions(+), 121 deletions(-) delete mode 100644 railties/lib/rails/tasks/documentation.rake diff --git a/guides/source/command_line.md b/guides/source/command_line.md index 78f26ccefa..19ccdc5488 100644 --- a/guides/source/command_line.md +++ b/guides/source/command_line.md @@ -419,14 +419,6 @@ The most common tasks of the `db:` Rake namespace are `migrate` and `create`, an More information about migrations can be found in the [Migrations](migrations.html) guide. -### `doc` - -The `doc:` namespace has the tools to generate documentation for your app, API documentation, guides. Documentation can also be stripped which is mainly useful for slimming your codebase, like if you're writing a Rails application for an embedded platform. - -* `rake doc:app` generates documentation for your application in `doc/app`. -* `rake doc:guides` generates Rails guides in `doc/guides`. -* `rake doc:rails` generates API documentation for Rails in `doc/api`. - ### `notes` `rake notes` will search through your code for comments beginning with FIXME, OPTIMIZE or TODO. The search is done in files with extension `.builder`, `.rb`, `.rake`, `.yml`, `.yaml`, `.ruby`, `.css`, `.js` and `.erb` for both default and custom annotations. diff --git a/guides/source/getting_started.md b/guides/source/getting_started.md index 31f2d2ed2f..ee742a0db7 100644 --- a/guides/source/getting_started.md +++ b/guides/source/getting_started.md @@ -2054,19 +2054,6 @@ resources: * The [Ruby on Rails mailing list](http://groups.google.com/group/rubyonrails-talk) * The [#rubyonrails](irc://irc.freenode.net/#rubyonrails) channel on irc.freenode.net -Rails also comes with built-in help that you can generate using the rake -command-line utility: - -* Running `rake doc:guides` will put a full copy of the Rails Guides in the - `doc/guides` folder of your application. Open `doc/guides/index.html` in your - web browser to explore the Guides. -* Running `rake doc:rails` will put a full copy of the API documentation for - Rails in the `doc/api` folder of your application. Open `doc/api/index.html` - in your web browser to explore the API documentation. - -TIP: To be able to generate the Rails Guides locally with the `doc:guides` rake -task you need to install the Redcarpet and Nokogiri gems. Add it to your `Gemfile` and run -`bundle install` and you're ready to go. Configuration Gotchas --------------------- diff --git a/rails.gemspec b/rails.gemspec index b3143e6fe1..1398169922 100644 --- a/rails.gemspec +++ b/rails.gemspec @@ -16,7 +16,7 @@ Gem::Specification.new do |s| s.email = 'david@loudthinking.com' s.homepage = 'http://www.rubyonrails.org' - s.files = ['README.md'] + Dir['guides/**/*'] - Dir['guides/output/**/*'] + s.files = ['README.md'] s.add_dependency 'activesupport', version s.add_dependency 'actionpack', version diff --git a/railties/CHANGELOG.md b/railties/CHANGELOG.md index a3f24f854d..8c536982fc 100644 --- a/railties/CHANGELOG.md +++ b/railties/CHANGELOG.md @@ -1,3 +1,7 @@ +* Remove the documentation tasks `doc:app`, `doc:rails`, and `doc:guides`. + + *Xavier Noria* + * Force generated routes to be inserted into routes.rb *Andrew White* diff --git a/railties/lib/rails/api/task.rb b/railties/lib/rails/api/task.rb index 4d49244807..a082932632 100644 --- a/railties/lib/rails/api/task.rb +++ b/railties/lib/rails/api/task.rb @@ -152,19 +152,5 @@ module Rails File.read('RAILS_VERSION').strip end end - - class AppTask < Task - def component_root_dir(gem_name) - $:.grep(%r{#{gem_name}[\w.-]*/lib\z}).first[0..-5] - end - - def api_dir - 'doc/api' - end - - def rails_version - Rails::VERSION::STRING - end - end end end diff --git a/railties/lib/rails/generators/app_base.rb b/railties/lib/rails/generators/app_base.rb index 057c8b0aec..253272c7dd 100644 --- a/railties/lib/rails/generators/app_base.rb +++ b/railties/lib/rails/generators/app_base.rb @@ -113,7 +113,6 @@ module Rails assets_gemfile_entry, javascript_gemfile_entry, jbuilder_gemfile_entry, - sdoc_gemfile_entry, psych_gemfile_entry, @extra_entries].flatten.find_all(&@gem_filter) end @@ -265,11 +264,6 @@ module Rails GemfileEntry.version('jbuilder', '~> 2.0', comment) end - def sdoc_gemfile_entry - comment = 'bundle exec rake doc:rails generates the API under doc/api.' - GemfileEntry.new('sdoc', '~> 0.4.0', comment, group: :doc) - end - def coffee_gemfile_entry comment = 'Use CoffeeScript for .coffee assets and views' if options.dev? || options.edge? diff --git a/railties/lib/rails/generators/rails/app/templates/README.rdoc b/railties/lib/rails/generators/rails/app/templates/README.rdoc index dd4e97e22e..db0fbe031b 100644 --- a/railties/lib/rails/generators/rails/app/templates/README.rdoc +++ b/railties/lib/rails/generators/rails/app/templates/README.rdoc @@ -22,7 +22,3 @@ Things you may want to cover: * Deployment instructions * ... - - -Please feel free to use a different markup language if you do not plan to run -rake doc:app. diff --git a/railties/lib/rails/tasks/documentation.rake b/railties/lib/rails/tasks/documentation.rake deleted file mode 100644 index 8544890553..0000000000 --- a/railties/lib/rails/tasks/documentation.rake +++ /dev/null @@ -1,70 +0,0 @@ -begin - require 'rdoc/task' -rescue LoadError - # Rubinius installs RDoc as a gem, and for this interpreter "rdoc/task" is - # available only if the application bundle includes "rdoc" (normally as a - # dependency of the "sdoc" gem.) - # - # If RDoc is not available it is fine that we do not generate the tasks that - # depend on it. Just be robust to this gotcha and go on. -else - require 'rails/api/task' - - # Monkey-patch to remove redoc'ing and clobber descriptions to cut down on rake -T noise - class RDocTaskWithoutDescriptions < RDoc::Task - include ::Rake::DSL - - def define - task rdoc_task_name - - task rerdoc_task_name => [clobber_task_name, rdoc_task_name] - - task clobber_task_name do - rm_r rdoc_dir rescue nil - end - - task :clobber => [clobber_task_name] - - directory @rdoc_dir - task rdoc_task_name => [rdoc_target] - file rdoc_target => @rdoc_files + [Rake.application.rakefile] do - rm_r @rdoc_dir rescue nil - @before_running_rdoc.call if @before_running_rdoc - args = option_list + @rdoc_files - if @external - argstring = args.join(' ') - sh %{ruby -Ivendor vendor/rd #{argstring}} - else - require 'rdoc/rdoc' - RDoc::RDoc.new.document(args) - end - end - self - end - end - - namespace :doc do - RDocTaskWithoutDescriptions.new("app") { |rdoc| - rdoc.rdoc_dir = 'doc/app' - rdoc.template = ENV['template'] if ENV['template'] - rdoc.title = ENV['title'] || "Rails Application Documentation" - rdoc.options << '--line-numbers' - rdoc.options << '--charset' << 'utf-8' - rdoc.rdoc_files.include('README.rdoc') - rdoc.rdoc_files.include('app/**/*.rb') - rdoc.rdoc_files.include('lib/**/*.rb') - } - Rake::Task['doc:app'].comment = "Generate docs for the app -- also available doc:rails, doc:guides (options: TEMPLATE=/rdoc-template.rb, TITLE=\"Custom Title\")" - - # desc 'Generate documentation for the Rails framework.' - Rails::API::AppTask.new('rails') - end -end - -namespace :doc do - task :guides do - rails_gem_dir = Gem::Specification.find_by_name("rails").gem_dir - require File.expand_path(File.join(rails_gem_dir, "/guides/rails_guides")) - RailsGuides::Generator.new(Rails.root.join("doc/guides")).generate - end -end diff --git a/railties/test/generators/app_generator_test.rb b/railties/test/generators/app_generator_test.rb index 689173f184..8cef40b151 100644 --- a/railties/test/generators/app_generator_test.rb +++ b/railties/test/generators/app_generator_test.rb @@ -417,11 +417,6 @@ class AppGeneratorTest < Rails::Generators::TestCase end end - def test_inclusion_of_doc - run_generator - assert_file 'Gemfile', /gem 'sdoc',\s+'~> 0.4.0',\s+group: :doc/ - end - def test_template_from_dir_pwd FileUtils.cd(Rails.root) assert_match(/It works from file!/, run_generator([destination_root, "-m", "lib/template.rb"])) -- cgit v1.2.3