feat: Generate inline snippets in yardoc #627
Conversation
google-cla
bot
added
the
cla: yes
| @@ -10,6 +10,7 @@ | |||
| # | |||
| <%= render partial: "service/client/method/docs/error", locals: { method: method } -%> | |||
| # | |||
| <%= render partial: "service/client/method/docs/snippets", locals: { method: method } -%> | |||
There was a problem hiding this comment.
my personal pref would be to have <%- if method.generate_yardoc_snippets? -%> here instead of in the subtemplate because then it can be seen that this part may not be rendered and the question of 'why is there no # after this render' does not come up.
There was a problem hiding this comment.
I think there are trade-offs. Putting the "if"s here would tend to obfuscate the structure a bit, and the question of the missing # will be there regardless.
| "ruby-cloud-yard-strict" => ":gem.:yard_strict", | ||
| "ruby-cloud-generic-endpoint" => ":gem.:generic_endpoint", | ||
| "ruby-cloud-generate-metadata" => ":generate_metadata", | ||
| "ruby-cloud-generate-standalone-snippets" => ":generate_standalone_snippets", |
There was a problem hiding this comment.
I try to add all new parameters into the shared/test_resources/api_test_resources.rb and the corresponding test cases because it then becomes easy to look at the whole tree of all the parameters filled.
Don't know if you want to do it or not, I can definitely do it myself later.
There was a problem hiding this comment.
I see. Let's do that in a separate PR. I think it could get kinda large.
There was a problem hiding this comment.
Opened #630 to remind us of this.
|
A similar work should probably be done for the snippets, e.g. update |
|
Yes, good call-out on snippets for the REST clients. I'll file an issue for that and work on it probably early next week. |
@examplesection to each RPC method demonstrating basic usage. The content of the example is the same as the standalone snippet we already have. This section is activated by the config:generate_yardoc_snippets.ruby-cloud-generate-standalone-snippetsandruby-cloud-generate-yardoc-snippetsso we can activate snippet generation from the bazel configs.document_ai_v1beta3rake tasks, which were leftover from testing an earlier PR, but are not currently configured to actually work, and indeed are currently causingbundle exec rake gento crash.