API Documentation

[tra38]

With Calyx almost ready for a 1.0 release, it does seem that documentation will need to be something to focus on.

I do think our current README is understandable, as it stands, but maybe I'm too used to the gem to really know whether the docs actually explain anything. And, of course, maybe a README may not be enough to show how Calyx can be used (and we may need to include a tutorial as well...but that might be overkill).

[maetl]

A big chunk of this was done in 1859eb4b4002f928bef3fb4bbe0bfbcf6912c865 and all the commits on 2016-07-04.

Autogenerated API docs available here: http://www.rubydoc.info/gems/calyx

Is there anything else missing that might be useful or important?

[tra38]

It could be useful to provide an example where a user can engage in indirection (showing that the output of a rule could be a symbol that refers to yet another rule, for instance).

Another possible addition is to show how to "use" Calyx's new features in interesting ways, so that the reader knows why these features are important in the first place. As an example, this was some quick code that I wrote up for a presentation tomorrow about how to use Calyx for "data-driven narratives", and while the code isn't exactly pretty, it's probably far more organized than what I was working with before.

require 'calyx'

class StockReporter < Calyx::Grammar
  good_stock "You should buy stock in {name} because this company has a low EPS."
  bad_stock "You should sell stock in {name} because this company has a high EPS."
end

def evaluator(params)
  stock_reporter = StockReporter.new
  if params[:eps] <= 50
    stock_reporter.generate(params, :good_stock)
  else
    stock_reporter.generate(params, :bad_stock)
  end
end

mitsui = { :name => "Mitsui", :eps => 15.8}
evaluator(mitsui)
# => "You should buy stock in Mitsui because this company has a low EPS."

Other than that, I think the documentation is complete and ready to be launched! Good job.

[maetl]

It could be useful to provide an example where a user can engage in indirection (showing that the output of a rule could be a symbol, for instance).

Great feedback. I agree this isn’t explained as well as it could be, and takes a bit of discovery to realise what is possible.

I’ll think about how to add explanations of use cases for some of the features.

[tra38]

If you are having trouble thinking about how to add explanations, would it be okay if I decide to write some documentation of "use cases" for advanced features, and then submit a PR to link that documentation (so you can review it to see if there's anything else that needs to be added)?

I'd like to know before I start, since I don't want to write something that might overlap with your work.

[maetl]

Not having trouble, just haven’t had time this week to get to this (sorry!).

I’m considering making a documentation website, and moving some of the stuff from the README into that format. I haven’t decided on the overall structure yet though.

For now, improving the examples in the README and adding use cases would be great. If you’re unsure whether or not it fits in, maybe post some examples/ideas on this thread, and we can work through it.

[maetl]

An alternative to your example above is to integrate the custom evaluator method with the class.

require 'calyx'

class StockReporter < Calyx::Grammar
  good_stock "You should buy stock in {name} because this company has a low EPS."
  bad_stock "You should sell stock in {name} because this company has a high EPS."

  def evaluator(params)
    if params[:eps] <= 50
      generate(params, :good_stock)
    else
      generate(params, :bad_stock)
    end
  end
end

stock_reporter = StockReporter.new
mitsui = { :name => "Mitsui", :eps => 15.8}
stock_reporter.evaluator(mitsui)
# => "You should buy stock in Mitsui because this company has a low EPS."