docs: new synthtool generated README #645
Conversation
googlebot
added
the
cla: yes
README.md
Outdated
|
|
||
| [Cloud Storage](https://cloud.google.com/storage/docs) allows world-wide storage and retrieval of any amount of data at any time. You can use Google Cloud Storage for a range of scenarios including serving website content, storing data for archival and disaster recovery, or distributing large data objects to users via direct download. |
There was a problem hiding this comment.
Yeah, it would be really nice to hang onto this, I think. Not sure if putting the long description in the metadata or embedding it in a README.md.tpl file is the right path.
There was a problem hiding this comment.
I propose the late-game addition of readme-partials.yml, with a section introduction. This would give us the flexibility to gradually hand-write some portions of the API documentation, which I think we're going to inevitably want for our libraries.
There was a problem hiding this comment.
In this case it looks like it's copied from https://cloud.google.com/storage/docs/ verbatim.
There was a problem hiding this comment.
@bcoe I really think this is a great idea. We had a few issues come up in the past asking for this, even with nodejs-repo-tools.
|
Something that has always bugged me about the README's is that the link for the client API docs is not really in a convenient spot. IMO it should be available right at the start and I shouldn't need to scan the document for it. |
Codecov Report
@@ Coverage Diff @@
## master #645 +/- ##
=======================================
Coverage 97.94% 97.94%
=======================================
Files 9 9
Lines 874 874
Branches 99 99
=======================================
Hits 856 856
Misses 9 9
Partials 9 9Continue to review full report at Codecov.
|
.readme-partials.yaml
Outdated
| Cloud Storage for a range of scenarios including serving website content, | ||
| storing data for archival and disaster recovery, or distributing large data | ||
| objects to users via direct download. | ||
| quickstart_footer: |
There was a problem hiding this comment.
@JustinBeckwith @callmehiphop it's now possible to customize the README output with .readme-partials.yaml. Right now the supported keys are introduction (for a handwritten library intro), and quickstart_footer, allowing us to provide some shim code that actually makes the quickstart functional.
There was a problem hiding this comment.
With #647 landing, can we drop this?
refs: googleapis/google-cloud-node#2868 this PR regenerates our README using
synthtoolrather than node-repo-tools.It seems to be most of the way there, one thing that does jump out at me is the description isn't nearly as fleshed out ... I wonder if this grew organically over time; any thoughts about how to auto-generate the README with up-to-date samples, while maintaining a more useful description?
@busunkim96 thanks for all your help on this!