From 2f293f5e1bc14b8189d38424ef24d829fedd8743 Mon Sep 17 00:00:00 2001 From: Sebastian Thiel Date: Thu, 19 Mar 2015 11:00:44 +0100 Subject: [PATCH] docs(ul/dl): method features and general info * add method listing for various categories, like 'downloads' and 'uploads' * add general information on how to do downloads and uploads using various protocols Fixes #28 --- gen/youtube3/README.md | 16 ++++++++++++++++ gen/youtube3/src/lib.rs | 16 ++++++++++++++++ src/mako/lib/lib.mako | 40 ++++++++++++++++++++++++++++++++++++++-- src/mako/lib/mbuild.mako | 15 ++++++--------- src/mako/lib/util.py | 6 ++++++ 5 files changed, 82 insertions(+), 11 deletions(-) diff --git a/gen/youtube3/README.md b/gen/youtube3/README.md index 03e625157a..e903c930cb 100644 --- a/gen/youtube3/README.md +++ b/gen/youtube3/README.md @@ -27,6 +27,18 @@ Handle the following *Resources* with ease from the central [hub](http://byron.g * [videos](http://byron.github.io/google-apis-rs/youtube3/struct.Video.html) ([*delete*](http://byron.github.io/google-apis-rs/youtube3/struct.VideoDeleteMethodBuilder.html), [*get rating*](http://byron.github.io/google-apis-rs/youtube3/struct.VideoGetRatingMethodBuilder.html), [*insert*](http://byron.github.io/google-apis-rs/youtube3/struct.VideoInsertMethodBuilder.html), [*list*](http://byron.github.io/google-apis-rs/youtube3/struct.VideoListMethodBuilder.html), [*rate*](http://byron.github.io/google-apis-rs/youtube3/struct.VideoRateMethodBuilder.html) and [*update*](http://byron.github.io/google-apis-rs/youtube3/struct.VideoUpdateMethodBuilder.html)) * watermarks ([*set*](http://byron.github.io/google-apis-rs/youtube3/struct.WatermarkSetMethodBuilder.html) and [*unset*](http://byron.github.io/google-apis-rs/youtube3/struct.WatermarkUnsetMethodBuilder.html)) +Upload supported by ... + +* [*set watermarks*](http://byron.github.io/google-apis-rs/youtube3/struct.WatermarkSetMethodBuilder.html) +* [*insert channel banners*](http://byron.github.io/google-apis-rs/youtube3/struct.ChannelBannerInsertMethodBuilder.html) +* [*set thumbnails*](http://byron.github.io/google-apis-rs/youtube3/struct.ThumbnailSetMethodBuilder.html) +* [*insert videos*](http://byron.github.io/google-apis-rs/youtube3/struct.VideoInsertMethodBuilder.html) + +Subscription supported by ... + +* [*list playlist items*](http://byron.github.io/google-apis-rs/youtube3/struct.PlaylistItemListMethodBuilder.html) + + Everything else about the *YouTube* *v3* API can be found at the [official documentation site](https://developers.google.com/youtube/v3). @@ -135,6 +147,10 @@ the doit() methods, or handed as possibly intermediate results to either the When delegates handle errors or intermediate values, they may have a chance to instruct the system to retry. This makes the system potentially resilient to all kinds of errors. +## About Uploads and Downlods + +TODO: 'alt' media for downloads, custom methods for uploads (simple, resumable) + ## About Customization/Callbacks You may alter the way an `doit()` method is called by providing a [delegate](http://byron.github.io/google-apis-rs/youtube3/cmn/trait.Delegate.html) to the diff --git a/gen/youtube3/src/lib.rs b/gen/youtube3/src/lib.rs index fa16feacb7..b8f5cb2b59 100644 --- a/gen/youtube3/src/lib.rs +++ b/gen/youtube3/src/lib.rs @@ -26,6 +26,18 @@ //! * [videos](struct.Video.html) ([*delete*](struct.VideoDeleteMethodBuilder.html), [*get rating*](struct.VideoGetRatingMethodBuilder.html), [*insert*](struct.VideoInsertMethodBuilder.html), [*list*](struct.VideoListMethodBuilder.html), [*rate*](struct.VideoRateMethodBuilder.html) and [*update*](struct.VideoUpdateMethodBuilder.html)) //! * watermarks ([*set*](struct.WatermarkSetMethodBuilder.html) and [*unset*](struct.WatermarkUnsetMethodBuilder.html)) //! +//! Upload supported by ... +//! +//! * [*set watermarks*](struct.WatermarkSetMethodBuilder.html) +//! * [*insert channel banners*](struct.ChannelBannerInsertMethodBuilder.html) +//! * [*set thumbnails*](struct.ThumbnailSetMethodBuilder.html) +//! * [*insert videos*](struct.VideoInsertMethodBuilder.html) +//! +//! Subscription supported by ... +//! +//! * [*list playlist items*](struct.PlaylistItemListMethodBuilder.html) +//! +//! //! Everything else about the *YouTube* *v3* API can be found at the //! [official documentation site](https://developers.google.com/youtube/v3). //! @@ -137,6 +149,10 @@ //! When delegates handle errors or intermediate values, they may have a chance to instruct the system to retry. This //! makes the system potentially resilient to all kinds of errors. //! +//! ## About Uploads and Downlods +//! +//! TODO: 'alt' media for downloads, custom methods for uploads (simple, resumable) +//! //! ## About Customization/Callbacks //! //! You may alter the way an `doit()` method is called by providing a [delegate](cmn/trait.Delegate.html) to the diff --git a/src/mako/lib/lib.mako b/src/mako/lib/lib.mako index 93d7b25f6c..5592a0cbae 100644 --- a/src/mako/lib/lib.mako +++ b/src/mako/lib/lib.mako @@ -4,7 +4,8 @@ PART_MARKER_TRAIT, RESOURCE_MARKER_TRAIT, METHOD_BUILDER_MARKERT_TRAIT, find_fattest_resource, build_all_params, pass_through, parts_from_params, REQUEST_MARKER_TRAIT, RESPONSE_MARKER_TRAIT, supports_scopes, to_api_version, - to_fqan) %>\ + to_fqan, METHODS_RESOURCE, ADD_PARAM_MEDIA_EXAMPLE, PROTOCOL_TYPE_INFO, enclose_in, + upload_action_fn) %>\ <%namespace name="util" file="util.mako"/>\ <%namespace name="mbuild" file="mbuild.mako"/>\ @@ -38,6 +39,17 @@ api_version = to_api_version(version) if api_version[0].isdigit(): api_version = 'v' + api_version + + + upload_methods, download_methods, subscription_methods = list(), list(), list() + for m in c.fqan_map.values(): + for array, param in ((download_methods, 'supportsMediaDownload'), + (upload_methods, 'supportsMediaUpload'), + (subscription_methods, 'supportsSubscription')): + if m.get(param, False): + array.append(m) + # end for each method + header_methods = (('Upload', upload_methods), ('Download', download_methods), ('Subscription', subscription_methods)) %>\ % if rust_doc: This documentation was generated from *${util.canonical_name()}* crate version *${cargo.build_version}*. @@ -62,6 +74,23 @@ Handle the following *Resources* with ease from the central ${link('hub', hub_ur * ${md_resource} (${put_and(md_methods)}) % endfor +% for method_type, methods in header_methods: +% if methods: +${method_type} supported by ... + +% for m in methods: +<% + _, resource, method = activity_split(m.id) + name_parts = [split_camelcase_s(method)] + if resource != METHODS_RESOURCE: + name_parts.append(split_camelcase_s(resource)) +%>\ +* ${link('*%s*' % ' '.join(name_parts), 'struct.%s.html' % mb_type(resource, method))} +% endfor ## for each method + +% endif ## if methods +% endfor ## for each method type + % if documentationLink: Everything else about the *${util.canonical_name()}* *${api_version}* API can be found at the [official documentation site](${documentationLink}). @@ -133,8 +162,15 @@ When delegates handle errors or intermediate values, they may have a chance to i makes the system potentially resilient to all kinds of errors. ${'##'} About Uploads and Downlods +If a method supports downloads, the response body, which is part of the ${link('Result', 'cmn/enum.Result.html')}, should be +read by you to obtain the media. +If such a method also supports a ${link('Response Result', 'cmn/trait.ResponseResult.html')}, it will return that by default. +You can see it as meta-data for the actual media. To trigger a media download, you will have to set up the builder by making +this call: `${ADD_PARAM_MEDIA_EXAMPLE}`. -TODO: 'alt' media for downloads, custom methods for uploads (simple, resumable) +Methods supporting uploads can do so using up to ${len(PROTOCOL_TYPE_INFO)} different protocols: +${put_and(md_italic(PROTOCOL_TYPE_INFO.keys()))}. The distinctiveness of each is represented by customized +`${api.terms.action}(...)` methods, which are then named ${put_and(enclose_in('`', ("%s(...)" % upload_action_fn(api.terms.upload_action, v['suffix']) for v in PROTOCOL_TYPE_INFO.values())))} respectively. ${'##'} About Customization/Callbacks diff --git a/src/mako/lib/mbuild.mako b/src/mako/lib/mbuild.mako index 4774dea1c0..2040bfef15 100644 --- a/src/mako/lib/mbuild.mako +++ b/src/mako/lib/mbuild.mako @@ -9,7 +9,7 @@ hub_type_params_s, method_media_params, enclose_in, mb_type_bounds, method_response, METHOD_BUILDER_MARKERT_TRAIT, pass_through, markdown_rust_block, parts_from_params, DELEGATE_PROPERTY_NAME, struct_type_bounds_s, supports_scopes, scope_url_to_variant, - re_find_replacements) + re_find_replacements, ADD_PARAM_FN, ADD_PARAM_MEDIA_EXAMPLE, upload_action_fn) def get_parts(part_prop): if not part_prop: @@ -34,9 +34,6 @@ if is_repeated_property(p): fn_name = 'add_' + fn_name return fn_name - - add_param_fn = 'param' - %>\ <%namespace name="util" file="util.mako"/>\ <%namespace name="lib" file="lib.mako"/>\ @@ -65,8 +62,8 @@ ${m.description | rust_doc_comment} /// % endif % if m.get('supportsMediaDownload', False): -/// This method supports **media download**. To enable it, set the *alt* parameter to *media*, .i.e. -/// `.${add_param_fn}("alt", "media")`. +/// This method supports **media download**. To enable it, adjust the builder like this: +/// `${ADD_PARAM_MEDIA_EXAMPLE}`. % if response_schema: /// Please note that due to missing multi-part support on the server side, you will only receive the media, /// but not the `${response_schema.id}` structure that you would usually get. The latter will be a default value. @@ -148,7 +145,7 @@ ${self._setter_fn(resource, method, m, p, part_prop, ThisType, c)}\ /// * *${opn}* (${op.location}-${op.type}) - ${op.description} % endfor % endif - pub fn ${add_param_fn}(mut self, name: T, value: T) -> ${ThisType} + pub fn ${ADD_PARAM_FN}(mut self, name: T, value: T) -> ${ThisType} where T: Str { self.${api.properties.params}.insert(name.as_slice().to_string(), value.as_slice().to_string()); self @@ -285,7 +282,7 @@ ${self._setter_fn(resource, method, m, p, part_prop, ThisType, c)}\ index = -1 if media_params[-1].max_size < 100*1024*1024: index = 0 - action_name = api.terms.upload_action + media_params[index].type.suffix + action_name = upload_action_fn(api.terms.upload_action, media_params[index].type.suffix) else: action_name = api.terms.action action_args = media_params and media_params[-1].type.example_value or '' @@ -754,7 +751,7 @@ if enable_resource_parsing \ % for item_name, item in p.info.iteritems(): /// * *${split_camelcase_s(item_name)}*: ${isinstance(item, (list, tuple)) and put_and(enclose_in("'", item)) or str(item)} % endfor - pub fn ${api.terms.upload_action}${p.type.suffix}<${mtype_param}>(self, ${p.type.arg_name}: ${mtype_param}, mime_type: mime::Mime) -> ${rtype} + pub fn ${upload_action_fn(api.terms.upload_action, p.type.suffix)}<${mtype_param}>(self, ${p.type.arg_name}: ${mtype_param}, mime_type: mime::Mime) -> ${rtype} where ${mtype_param}: ${mtype_where} { self.${api.terms.action}(\ % for _ in range(0, loop.index): diff --git a/src/mako/lib/util.py b/src/mako/lib/util.py index e748f90d8a..fe26fa086f 100644 --- a/src/mako/lib/util.py +++ b/src/mako/lib/util.py @@ -54,6 +54,9 @@ INS_METHOD = 'insert' DEL_METHOD = 'delete' METHODS_RESOURCE = 'methods' +ADD_PARAM_FN = 'param' +ADD_PARAM_MEDIA_EXAMPLE = "." + ADD_PARAM_FN + '("alt", "media")' + SPACES_PER_TAB = 4 NESTED_TYPE_SUFFIX = 'item' @@ -821,6 +824,9 @@ def get_word(d, n, e = ''): def property(n): return '_' + mangle_ident(n) +def upload_action_fn(upload_action_term, suffix): + return upload_action_term + suffix + # n = 'foo.bar.Baz' -> 'FooBarBaz' def dot_sep_to_canonical_type_name(n): return ''.join(canonical_type_name(singular(t)) for t in n.split('.'))