Docs refactoring

[muellerj]

Move the template descriptions into their ./lib/tilt/*.rb files and link to these from the README

[muellerj]

@jeremyevans please have a look if this is the direction you were intending. I haven't quite finished looking over all the template docs, but I would ultimately like to move everything out of TEMPLATES.md (and delete the latter subsequently).

I'll squash everything into a single commit unless you want small granular commits?

[muellerj]

In particular, I'm not sure where/how to split the different ERB template documentations. Are there two implementations in the standard library (erb, erbrb)?

[jeremyevans]

Thank you very much for working on this. For erb, have the general documentation in the erubi.rb template file as it is the default, with only erb-engine specific information in the erb.rb file.

[muellerj]

I'm done with the initial move - could you please check the assignment for the ERB and Markdown templates in particular?

[muellerj]

@jeremyevans If you have changes that need to go into this PR, please feel free to commit to this branch

[jeremyevans]

This looks great, thank you! A few minor things I noticed:

• Probably should use a more advanced rdoc task (example from Erubi: https://github.com/jeremyevans/erubi/blob/master/Rakefile#L16-L36)

• Some of the template file documentation still uses markdown syntax instead of rdoc syntax, mostly for backticks, maybe for other things. Best to switch these to use rdoc syntax.

• In the file-level documentation for the template, you should reference the template class name, so that you can click on the link in the README to get the general information for the template, and then click the template class name to get the API documentation for that template class. In Sequel, I used the term "Related module" for this (example: https://sequel.jeremyevans.net/rdoc-plugins/files/lib/sequel/extensions/pg_array_rb.html)

[muellerj]

Thanks for your guidance, a pleasure to help. I have integrated these changes - one question about the related modules remains in my mind:

For classes, which are defined in the following manner, the RDoc refernences work fine:

module Tilt
  class ERBTemplate < Template
    # ...
  end
end

For classes, which assign a constant via Tilt::StaticTemplate.subclass or directly from a Template, RDoc fails to generate proper links.

Tilt::SlimTemplate = Slim::Template

See rdoc/files/lib/tilt/commonmarker_rb.html for example.

How would you like me to proceed with these?

[jeremyevans]

Thanks for your guidance, a pleasure to help. I have integrated these changes - one question about the related modules remains in my mind:

For classes, which are defined in the following manner, the RDoc refernences work fine:

module Tilt
  class ERBTemplate < Template
    # ...
  end
end

For classes, which assign a constant via Tilt::StaticTemplate.subclass or directly from a Template, RDoc fails to generate proper links.

Tilt::SlimTemplate = Slim::Template

See rdoc/files/lib/tilt/commonmarker_rb.html for example.

How would you like me to proceed with these?

I think we should not include the Related module in this case. It's fine to do so as there are no documentable methods.

Thank you again for working on this. After the removal of the Related module for those templates, this looks good to merge. Then I'll setup a website to host the documentation.

[muellerj]

Looks good to me, go ahead at your discretion!

[jeremyevans]

Merged at e109816. Will work on the website tomorrow. Thank you again for your patience and work in getting these changes prepared.

[jeremyevans]

Website now up: https://tilt.jeremyevans.net/