All writers now inherit from a base writer

[alenia]

• the writers are now responsible for cleaning docs
• added an append_json writer that does not delete docs and simply modifies index.json

Example of use

in lib/tasks/my_docs.rspec:

RSpec::Core::RakeTask.new('mydocs:generate', :spec_file) do |t, task_args|
  if spec_file = task_args[:spec_file]
    ENV["DOC_FORMAT"] = "append_json"
  end
  t.pattern    = spec_file || 'spec/acceptance/**/*_spec.rb'
  t.rspec_opts = ["--format RspecApiDocumentation::ApiFormatter"]
end

in spec/support/documentation.rb

ENV["DOC_FORMAT"] ||= "json"

RspecApiDocumentation.configure do |config|
  config.format    = ENV["DOC_FORMAT"]
end

then when I run rake mydocs:generate[spec/acceptance/foo_spec.rb], I only generate output relevant to foo.

[alenia]

tagging @lanej

[oestrich]

My only concern with having writers clear the docs is using multiple formats at once. It's pretty minor since the folder would just be cleared more than once. I would also like to have a warning about AppendJsonWriter needed to be run by itself in the README after merging (I can take care of this, just want to make sure I remember).

I'm not sure AppendJsonWriter makes sense to me. I would guess you could do something very similar by writing a rake task similar to the one you list above with just the JSON format. It should only output specs in the foo_spec.rb file, no?

[alenia]

Without the AppendJsonWriter, the index would be blown away everytime we regenerate docs. If we want to be able to use the index, we need some way to add the references to any added scenarios. It does the same thing as the JsonWriter for all of the other files, hence it inherits from it. The only implementation difference is in how the index is built.

[lanej]

@oestrich we have fairly extensive documentation specs written and takes a substantial amount of time to run the entire suite. This allows us to target specific files that have changed, enabling us to scale with this tool.

[oestrich]

Ok, that makes sense and is a good reason for this. Just looking for some clarification. Merging.

[lanej]

thanks @oestrich