mirrors
/
rails
mirror of https://github.com/rails/rails
8
0
Fork 0
Code Issues Projects Releases Wiki Activity

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.
This commit is contained in:
Xavier Noria 2015-02-06 20:06:29 +01:00
parent 8c752c7ac7
commit cd7cc5254b
9 changed files with 5 additions and 121 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

8
guides/source/command_line.md
View File

@ -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.

13
guides/source/getting_started.md
View File

@ -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
---------------------

2
rails.gemspec
View File

@ -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

4
railties/CHANGELOG.md
View File

@ -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*

14
railties/lib/rails/api/task.rb
View File

@ -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

6
railties/lib/rails/generators/app_base.rb
View File

@ -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?

4
railties/lib/rails/generators/rails/app/templates/README.rdoc
View File

@ -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
<tt>rake doc:app</tt>.

70
railties/lib/rails/tasks/documentation.rake
View File

@ -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

5
railties/test/generators/app_generator_test.rb
View File

@ -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"]))