Autogenerate README based on description.md

[ghost]

Why?

According to the docs, README are auto-generated but that is not the case: https://github.com/exercism/ruby#readmes

Manually copy-pasting README from problem-specifications can lead to errors. This creates consistency across all READMEs.

What?

README is generated by combining:

1. https://github.com/exercism/problem-specifications/blob/master/exercises/accumulate/description.md
2. https://github.com/exercism/ruby/blob/master/docs/EXERCISE_README_INSERT.md

How Has This Been Tested?

rake test
./bin/generate

Types of changes

• Add build_readme to generator
• Add unit tests for generator
• Run generator across all tests to create uniform READMEs

Checklist:

• I have read the CONTRIBUTING document.
• I have added tests to cover my changes.
• All new and existing tests passed.

[Insti]

Why have all the titles disappeared?

[ghost]

The titles disappeared because the original problem-specfications/description.md don't have it in them.

Accumulate README from problem-specfications:
https://github.com/exercism/problem-specifications/blob/master/exercises/accumulate/description.md

Ruby's Accumulate README:
https://github.com/exercism/ruby/blob/master/exercises/accumulate/README.md

I was thinking about adding the titles into the description.md of problem-specifications for every problem so that when generator gets run the titles don't disappear.

[Insti]

Please have a read through this thread an the associated issues/PRs:
exercism/problem-specifications#767

[Insti]

And: https://github.com/Insti/trackler/blob/master/lib/trackler/implementation.rb#L87
For the code that used to (/still does) generate the readmes.

[Insti]

Things are a bit more complicated than normal right now as we're trying to make sure that the exercises are compatible with both the existing exercism.io site and the new https://v2.exercism.io/ (nextercism) site that have slightly different requirements.
It is nextercism that requires that the track have local README.md files.

[Insti]

A tool to generate the readmes is good 👍

There was some talk of having configlet generate READMEs, I'm not sure how far that idea progressed. You might like to search the discussions in /meta /configlet /discussions
(there are a lot of repositories!)

[Insti]

I'd like to see better separation of commits here to make this easier to review.
at least:
1 commit for the README generator.
1 commit for the regeneration of all the exercise readmes.
(plus whatever else is relevant, the more atomic commits the better basically.)

[Insti]

docs: is not an appropriate argument here, the docs path should be derived from the track: EXERCISM_RUBY_ROOT

[Insti]

The underscores should not be here.

[Insti]

Why is this showing as completely new?

[ghost]

Okay, turns out that Configlet actually does the same thing that I was trying to do but it expects the user to run it manually. IE, READMEs are properly generated using:

./configlet generate . --only=sublist

I think a better approach is to add this command to run "confliget generate" command with Travis CI and automatically have READMEs pushed back to repository?

Places to change: https://github.com/exercism/ruby/blob/master/.travis.yml
Upload files after build is successful: https://gist.github.com/willprice/e07efd73fb7f13f917ea

Thoughts?

[Insti]

I think a better approach is to add this command to run "confliget generate" command with Travis CI and automatically have READMEs pushed back to repository?

This is premature I think. How about making the ruby track generate script call out to configlet to regenerate the readme?

[ghost]

How about making the ruby track generate script call out to configlet to regenerate the readme?

Yeah, that seems more reasonable

[Insti]

If possible do this as 2 pull requests.
1 that just adds the necessary generator changes.
and another that regenerates all the readmes. (You should be able to do this locally without having to have the generator changes merged.)

This will make things easier to review/test/merge.

[Insti]

On a philosophical level, I personally don't think having configlet generate the readmes is the right thing to do, but that's how things seem to be, so we'll go with that for now.

[ghost]

Calling configlet during generate: #722