Script for updating main README

[mderka]

While working on the documentation for the DNS, I am realizing that keeping the snippets, module-specific readme, and main readme consistent is quite difficult and time consuming. I wonder if for the future use, we could benefit from a script which would generate the main readme from the module specific ones. The main readme would look somewhat as follows:

Doing Magic
==========
{include magic-module:first-part}
{include magic-module:second-part}

The module specific one:

...
{block magic-module:first-part}
This is the first part...
{/block}
...
{block magic-module:second-part}
This is the second part...
{/block}
...

The script would simply do replacements making the main readme this:

Doing Magic
==========
This is the first part...
This is the second part...

and it would also erase annotations from the second module-specific readme.

[aozarov]

I think this is a fine idea. I also think this relates to #607.

It would be nice if we had a script to re-create the readme files based on readme templates and providing a way to reference/include code and other readme fragments.

It looks like GitHub is not going to enable that anytime soon, so providing a script that one could trigger manually would probably be good enough.

[mziccard]

This sounds like a very good idea!

[danoscarmike]

This has been added to our feature backlog: https://github.com/GoogleCloudPlatform/google-cloud-java/wiki/Feature-backlog. This issue will be closed but is linked in the backlog and can continue to be used for comment and discussion.