class ResourceDirective(Directive): has_content = True required_arguments = 0 option_spec = { 'classname': directives.unchanged_required, 'is-list': directives.flag, 'hide-links': directives.flag, 'hide-examples': directives.flag, } item_http_methods = set(['GET', 'DELETE', 'PUT']) list_http_methods = set(['GET', 'POST']) FILTERED_MIMETYPES = [ 'application/json', 'application/xml', ] type_mapping = { int: 'Integer', str: 'String', bool: 'Boolean', dict: 'Dictionary', file: 'Uploaded File', } def run(self): try: resource_class = self.get_resource_class(self.options['classname']) except ResourceNotFound, e: return e.error_node # Add the class's file and this extension to the dependencies. self.state.document.settings.env.note_dependency(__file__) self.state.document.settings.env.note_dependency( sys.modules[resource_class.__module__].__file__) resource = get_resource_from_class(resource_class) is_list = 'is-list' in self.options docname = 'webapi2.0-%s-resource' % \ get_resource_docname(resource, is_list) resource_title = get_resource_title(resource, is_list) targetnode = nodes.target('', '', ids=[docname], names=[docname]) self.state.document.note_explicit_target(targetnode) main_section = nodes.section(ids=[docname]) # Details section main_section += nodes.title(text=resource_title) main_section += self.build_details_table(resource) # Fields section if (resource.fields and (not is_list or resource.singleton)): fields_section = nodes.section(ids=['fields']) main_section += fields_section fields_section += nodes.title(text='Fields') fields_section += self.build_fields_table(resource.fields) # Links section if 'hide-links' not in self.options: fields_section = nodes.section(ids=['links']) main_section += fields_section fields_section += nodes.title(text='Links') fields_section += self.build_links_table(resource) # HTTP method descriptions for http_method in self.get_http_methods(resource, is_list): method_section = nodes.section(ids=[http_method]) main_section += method_section method_section += nodes.title(text='HTTP %s' % http_method) method_section += self.build_http_method_section(resource, http_method) if 'hide-examples' not in self.options: examples_section = nodes.section(ids=['examples']) examples_section += nodes.title(text='Examples') has_examples = False if is_list: allowed_mimetypes = resource.allowed_list_mimetypes else: allowed_mimetypes = resource.allowed_item_mimetypes for mimetype in allowed_mimetypes: if mimetype in self.FILTERED_MIMETYPES: # Resources have more specific mimetypes. We want to # filter out the general ones (like application/json) # so we don't show redundant examples. continue example_node = build_example( self.fetch_resource_data(resource, mimetype), mimetype) if example_node: example_section = nodes.section(ids=['example_' + mimetype]) examples_section += example_section example_section += nodes.title(text=mimetype) example_section += example_node has_examples = True if has_examples: main_section += examples_section return [targetnode, main_section]
class ResourceDirective(Directive): has_content = True required_arguments = 0 option_spec = { 'classname': directives.unchanged_required, 'is-list': directives.flag, 'hide-links': directives.flag, 'hide-examples': directives.flag, } item_http_methods = set(['GET', 'DELETE', 'PUT']) list_http_methods = set(['GET', 'POST']) FILTERED_MIMETYPES = [ 'application/json', 'application/xml', ] def run(self): try: resource_class = self.get_resource_class(self.options['classname']) except ResourceNotFound, e: return e.error_node # Add the class's file and this extension to the dependencies. env = self.state.document.settings.env env.note_dependency(__file__) env.note_dependency(sys.modules[resource_class.__module__].__file__) resource = get_resource_from_class(resource_class) is_list = 'is-list' in self.options docname = 'webapi2.0-%s-resource' % \ get_resource_docname(env.app, resource, is_list) resource_title = get_resource_title(resource, is_list) targetnode = nodes.target('', '', ids=[docname], names=[docname]) self.state.document.note_explicit_target(targetnode) main_section = nodes.section(ids=[docname]) # Main section main_section += nodes.title(text=resource_title) for attr_name, text_fmt in (('added_in', 'Added in %s'), ('deprecated_in', 'Deprecated in %s'), ('removed_in', 'Removed in %s')): version = getattr(resource, attr_name, None) if not version: if is_list: prefix = 'list_resource' else: prefix = 'item_resource' version = getattr(resource, '%s_%s' % (prefix, attr_name), None) if version: paragraph = nodes.paragraph() paragraph += nodes.emphasis(text=text_fmt % version, classes=['resource-versioning']) main_section += paragraph main_section += parse_text( self, inspect.getdoc(resource), where='%s class docstring' % self.options['classname']) if getattr(resource, 'required_features', False): required_features = nodes.important() required_features += nodes.inline( text='Using this resource requires extra features to be ' 'enabled on the server. See "Required Features" below.') main_section += required_features # Details section details_section = nodes.section(ids=['details']) main_section += details_section details_section += nodes.title(text='Details') details_section += self.build_details_table(resource) # Fields section if (resource.fields and (not is_list or resource.singleton)): fields_section = nodes.section(ids=['fields']) main_section += fields_section fields_section += nodes.title(text='Fields') fields_section += self.build_fields_table(resource.fields) # Links section if 'hide-links' not in self.options: fields_section = nodes.section(ids=['links']) main_section += fields_section fields_section += nodes.title(text='Links') fields_section += self.build_links_table(resource) # HTTP method descriptions for http_method in self.get_http_methods(resource, is_list): method_section = nodes.section(ids=[http_method]) main_section += method_section method_section += nodes.title(text='HTTP %s' % http_method) method_section += self.build_http_method_section(resource, http_method) if 'hide-examples' not in self.options: examples_section = nodes.section(ids=['examples']) examples_section += nodes.title(text='Examples') has_examples = False if is_list: mimetype_key = 'list' else: mimetype_key = 'item' for mimetype in resource.allowed_mimetypes: try: mimetype = mimetype[mimetype_key] except KeyError: continue if mimetype in self.FILTERED_MIMETYPES: # Resources have more specific mimetypes. We want to # filter out the general ones (like application/json) # so we don't show redundant examples. continue if mimetype.endswith('xml'): # JSON is preferred. While we support XML, let's not # continue to advertise it. continue url, headers, data = \ self.fetch_resource_data(resource, mimetype) example_node = build_example(headers, data, mimetype) if example_node: example_section = \ nodes.section(ids=['example_' + mimetype], classes=['examples', 'requests-example']) examples_section += example_section example_section += nodes.title(text=mimetype) accept_mimetype = mimetype if (mimetype.startswith('application/') and mimetype.endswith('+json')): # Instead of telling the user to ask for a specific # mimetype on the request, show them that asking for # application/json works fine. accept_mimetype = 'application/json' curl_text = ( '$ curl http://reviews.example.com%s -H "Accept: %s"' % (url, accept_mimetype) ) example_section += nodes.literal_block( curl_text, curl_text, classes=['cmdline']) example_section += nodes.literal_block( headers, headers, classes=['http-headers']) example_section += example_node has_examples = True if has_examples: main_section += examples_section return [targetnode, main_section]
class ResourceDirective(Directive): has_content = True required_arguments = 0 option_spec = { 'classname': directives.unchanged_required, 'is-list': directives.flag, 'hide-links': directives.flag, 'hide-examples': directives.flag, } item_http_methods = set(['GET', 'DELETE', 'PUT']) list_http_methods = set(['GET', 'POST']) FILTERED_MIMETYPES = [ 'application/json', 'application/xml', ] type_mapping = { int: 'Integer', str: 'String', unicode: 'String', bool: 'Boolean', dict: 'Dictionary', file: 'Uploaded File', } def run(self): try: resource_class = self.get_resource_class(self.options['classname']) except ResourceNotFound, e: return e.error_node # Add the class's file and this extension to the dependencies. self.state.document.settings.env.note_dependency(__file__) self.state.document.settings.env.note_dependency( sys.modules[resource_class.__module__].__file__) resource = get_resource_from_class(resource_class) is_list = 'is-list' in self.options docname = 'webapi2.0-%s-resource' % \ get_resource_docname(resource, is_list) resource_title = get_resource_title(resource, is_list) targetnode = nodes.target('', '', ids=[docname], names=[docname]) self.state.document.note_explicit_target(targetnode) main_section = nodes.section(ids=[docname]) # Main section main_section += nodes.title(text=resource_title) main_section += parse_text(self, inspect.getdoc(resource), where='%s class docstring' % self.options['classname']) # Details section details_section = nodes.section(ids=['details']) main_section += details_section details_section += nodes.title(text='Details') details_section += self.build_details_table(resource) # Fields section if (resource.fields and (not is_list or resource.singleton)): fields_section = nodes.section(ids=['fields']) main_section += fields_section fields_section += nodes.title(text='Fields') fields_section += self.build_fields_table(resource.fields) # Links section if 'hide-links' not in self.options: fields_section = nodes.section(ids=['links']) main_section += fields_section fields_section += nodes.title(text='Links') fields_section += self.build_links_table(resource) # HTTP method descriptions for http_method in self.get_http_methods(resource, is_list): method_section = nodes.section(ids=[http_method]) main_section += method_section method_section += nodes.title(text='HTTP %s' % http_method) method_section += self.build_http_method_section( resource, http_method) if 'hide-examples' not in self.options: examples_section = nodes.section(ids=['examples']) examples_section += nodes.title(text='Examples') has_examples = False if is_list: mimetype_key = 'list' else: mimetype_key = 'item' for mimetype in resource.allowed_mimetypes: try: mimetype = mimetype[mimetype_key] except KeyError: continue if mimetype in self.FILTERED_MIMETYPES: # Resources have more specific mimetypes. We want to # filter out the general ones (like application/json) # so we don't show redundant examples. continue if mimetype.endswith('xml'): # JSON is preferred. While we support XML, let's not # continue to advertise it. continue url, headers, data = \ self.fetch_resource_data(resource, mimetype) example_node = build_example(headers, data, mimetype) if example_node: example_section = \ nodes.section(ids=['example_' + mimetype], classes=['examples', 'requests-example']) examples_section += example_section example_section += nodes.title(text=mimetype) accept_mimetype = mimetype if (mimetype.startswith('application/') and mimetype.endswith('+json')): # Instead of telling the user to ask for a specific # mimetype on the request, show them that asking for # application/json works fine. accept_mimetype = 'application/json' curl_text = ('$ curl http://reviews.example.com%s -A %s' % (url, accept_mimetype)) example_section += nodes.literal_block(curl_text, curl_text, classes=['cmdline']) example_section += nodes.literal_block( headers, headers, classes=['http-headers']) example_section += example_node has_examples = True if has_examples: main_section += examples_section return [targetnode, main_section]
class WebApiDocsDirective(Directive): has_content = True required_arguments = 0 option_spec = { 'classname': directives.unchanged_required, 'is-list': directives.flag, 'hide-links': directives.flag, 'hide-examples': directives.flag, } item_http_methods = set(['GET', 'DELETE', 'PUT']) list_http_methods = set(['GET', 'POST']) type_mapping = { int: 'Integer', str: 'String', bool: 'Boolean', file: 'Uploaded File', } # Mapping of mimetypes to language names for syntax highlighting. mimetype_language_mapping = { 'application/json': 'javascript', 'application/xml': 'xml', 'text/x-patch': 'diff', FileDiffResource.DIFF_DATA_MIMETYPE_JSON: 'javascript', FileDiffResource.DIFF_DATA_MIMETYPE_XML: 'xml', } def run(self): try: resource_class = self.get_resource_class(self.options['classname']) except ResourceNotFound, e: return e.error_node # Add the class's file and this extension to the dependencies. self.state.document.settings.env.note_dependency(__file__) self.state.document.settings.env.note_dependency( sys.modules[resource_class.__module__].__file__) resource = get_resource_from_class(resource_class) is_list = 'is-list' in self.options docname = 'webapi2.0-%s-resource' % \ get_resource_docname(resource, is_list) resource_title = get_resource_title(resource, is_list) targetnode = nodes.target('', '', ids=[docname], names=[docname]) self.state.document.note_explicit_target(targetnode) main_section = nodes.section(ids=[docname]) # Details section main_section += nodes.title(text=resource_title) main_section += self.build_details_table(resource) # Fields section if (resource.fields and (not is_list or resource.singleton)): fields_section = nodes.section(ids=['fields']) main_section += fields_section fields_section += nodes.title(text='Fields') fields_section += self.build_fields_table(resource.fields) # Links section if 'hide-links' not in self.options: fields_section = nodes.section(ids=['links']) main_section += fields_section fields_section += nodes.title(text='Links') fields_section += self.build_links_table(resource) # HTTP method descriptions for http_method in self.get_http_methods(resource, is_list): method_section = nodes.section(ids=[http_method]) main_section += method_section method_section += nodes.title(text='HTTP %s' % http_method) method_section += self.build_http_method_section(resource, http_method) if 'hide-examples' not in self.options: examples_section = nodes.section(ids=['examples']) examples_section += nodes.title(text='Examples') has_examples = False if is_list: allowed_mimetypes = resource.allowed_list_mimetypes else: allowed_mimetypes = resource.allowed_item_mimetypes for mimetype in allowed_mimetypes: example_node = self.build_example(resource, mimetype) if example_node: example_section = nodes.section(ids=['example_' + mimetype]) examples_section += example_section example_section += nodes.title(text=mimetype) example_section += example_node has_examples = True if has_examples: main_section += examples_section return [targetnode, main_section]