Source code for wsmeext.sphinxext

import inspect
import re
import sys

import six

from sphinx import addnodes
from sphinx.ext import autodoc
from sphinx.domains.python import PyClasslike, PyClassmember
from sphinx.domains import Domain, ObjType
from sphinx.directives import ObjectDescription
from sphinx.util.docfields import Field
from sphinx.util.nodes import make_refnode

from sphinx.roles import XRefRole
from sphinx.locale import l_, _

from docutils.parsers.rst import Directive
from docutils.parsers.rst import directives

import wsme
import wsme.types
import wsme.rest.json
import wsme.rest.xml

field_re = re.compile(r':(?P<field>\w+)(\s+(?P<name>\w+))?:')


def datatypename(datatype):
    if isinstance(datatype, wsme.types.UserType):
        return datatype.name
    if isinstance(datatype, wsme.types.DictType):
        return 'dict(%s: %s)' % (datatypename(datatype.key_type),
                                 datatypename(datatype.value_type))
    if isinstance(datatype, wsme.types.ArrayType):
        return 'list(%s)' % datatypename(datatype.item_type)
    return datatype.__name__


def make_sample_object(datatype):
    if datatype is wsme.types.bytes:
        return six.b('samplestring')
    if datatype is wsme.types.text:
        return u'sample unicode'
    if datatype is int:
        return 5
    sample_obj = getattr(datatype, 'sample', datatype)()
    return sample_obj


def get_protocols(names):
    names = list(names)
    protocols = []
    if 'rest' in names:
        names.remove('rest')
        protocols.extend('restjson', 'restxml')
    if 'restjson' in names:
        names.remove('restjson')
        protocols.append(('Json', wsme.rest.json))
    if 'restxml' in names:
        names.remove('restxml')
        protocols.append(('XML', wsme.rest.xml))
    for name in names:
        p = wsme.protocol.getprotocol(name)
        protocols.append((p.displayname or p.name, p))
    return protocols


class SampleType(object):
    """A Sample Type"""

    #: A Int
    aint = int

    def __init__(self, aint=None):
        if aint:
            self.aint = aint

    @classmethod
    def sample(cls):
        return cls(10)


class SampleService(wsme.WSRoot):
    @wsme.expose(SampleType)
    @wsme.validate(SampleType, int, str)
[docs] def change_aint(data, aint, dummy='useless'): """ :param aint: The new value :return: The data object with its aint field value changed. """ data.aint = aint return data
def getroot(env, force=False): root = env.temp_data.get('wsme:root') if not force and root: return root rootpath = env.temp_data.get('wsme:rootpath', env.app.config.wsme_root) if rootpath is None: return None modname, classname = rootpath.rsplit('.', 1) __import__(modname) module = sys.modules[modname] root = getattr(module, classname) env.temp_data['wsme:root'] = root return root def scan_services(service, path=[]): has_functions = False for name in dir(service): if name.startswith('_'): continue a = getattr(service, name) if inspect.ismethod(a): if hasattr(a, '_wsme_definition'): has_functions = True if inspect.isclass(a): continue if len(path) > wsme.rest.APIPATH_MAXLEN: raise ValueError("Path is too long: " + str(path)) for value in scan_services(a, path + [name]): yield value if has_functions: yield service, path def find_service_path(env, service): root = getroot(env) if service == root: return [] for s, path in scan_services(root): if s == service: return path return None class TypeDirective(PyClasslike): def get_index_text(self, modname, name_cls): return _('%s (webservice type)') % name_cls[0] def add_target_and_index(self, name_cls, sig, signode): ret = super(TypeDirective, self).add_target_and_index( name_cls, sig, signode ) name = name_cls[0] types = self.env.domaindata['wsme']['types'] if name in types: self.state_machine.reporter.warning( 'duplicate type description of %s ' % name) types[name] = self.env.docname return ret class AttributeDirective(PyClassmember): doc_field_types = [ Field('datatype', label=l_('Type'), has_arg=False, names=('type', 'datatype')) ] def check_samples_slot(value): """Validate the samples_slot option to the TypeDocumenter. Valid positions are 'before-docstring' and 'after-docstring'. Using the explicit 'none' disables sample output. The default is after-docstring. """ if not value: return 'after-docstring' val = directives.choice( value, ('none', # do not include 'before-docstring', # show samples then docstring 'after-docstring', # show docstring then samples )) return val class TypeDocumenter(autodoc.ClassDocumenter): objtype = 'type' directivetype = 'type' domain = 'wsme' required_arguments = 1 default_samples_slot = 'after-docstring' option_spec = dict( autodoc.ClassDocumenter.option_spec, **{'protocols': lambda l: [v.strip() for v in l.split(',')], 'samples-slot': check_samples_slot, }) @staticmethod def can_document_member(member, membername, isattr, parent): # we don't want to be automaticaly used # TODO check if the member is registered an an exposed type return False def format_name(self): return self.object.__name__ def format_signature(self): return u'' def add_directive_header(self, sig): super(TypeDocumenter, self).add_directive_header(sig) # remove the :module: option that was added by ClassDocumenter if ':module:' in self.directive.result[-1]: self.directive.result.pop() def import_object(self): if super(TypeDocumenter, self).import_object(): wsme.types.register_type(self.object) return True else: return False def add_content(self, more_content, no_docstring=False): # Check where to include the samples samples_slot = self.options.samples_slot or self.default_samples_slot def add_docstring(): super(TypeDocumenter, self).add_content( more_content, no_docstring) def add_samples(): protocols = get_protocols( self.options.protocols or self.env.app.config.wsme_protocols ) content = [] if protocols: sample_obj = make_sample_object(self.object) content.extend([ l_(u'Data samples:'), u'', u'.. cssclass:: toggle', u'' ]) for name, protocol in protocols: language, sample = protocol.encode_sample_value( self.object, sample_obj, format=True) content.extend([ name, u' .. code-block:: ' + language, u'', ]) content.extend( u' ' * 8 + line for line in six.text_type(sample).split('\n')) for line in content: self.add_line(line, u'<wsmeext.sphinxext') self.add_line(u'', '<wsmeext.sphinxext>') if samples_slot == 'after-docstring': add_docstring() add_samples() elif samples_slot == 'before-docstring': add_samples() add_docstring() else: add_docstring() class AttributeDocumenter(autodoc.AttributeDocumenter): datatype = None domain = 'wsme' @staticmethod def can_document_member(member, membername, isattr, parent): return isinstance(parent, TypeDocumenter) def import_object(self): success = super(AttributeDocumenter, self).import_object() if success: self.datatype = self.object.datatype return success def add_content(self, more_content, no_docstring=False): self.add_line( u':type: %s' % datatypename(self.datatype), '<wsmeext.sphinxext>' ) self.add_line(u'', '<wsmeext.sphinxext>') super(AttributeDocumenter, self).add_content( more_content, no_docstring) def add_directive_header(self, sig): super(AttributeDocumenter, self).add_directive_header(sig) class RootDirective(Directive): """ This directive is to tell what class is the Webservice root """ has_content = False required_arguments = 1 optional_arguments = 0 final_argument_whitespace = False option_spec = { 'webpath': directives.unchanged } def run(self): env = self.state.document.settings.env rootpath = self.arguments[0].strip() env.temp_data['wsme:rootpath'] = rootpath if 'wsme:root' in env.temp_data: del env.temp_data['wsme:root'] if 'webpath' in self.options: env.temp_data['wsme:webpath'] = self.options['webpath'] return [] class ServiceDirective(ObjectDescription): name = 'service' optional_arguments = 1 def handle_signature(self, sig, signode): path = sig.split('/') namespace = '/'.join(path[:-1]) if namespace and not namespace.endswith('/'): namespace += '/' servicename = path[-1] if not namespace and not servicename: servicename = '/' signode += addnodes.desc_annotation('service ', 'service ') if namespace: signode += addnodes.desc_addname(namespace, namespace) signode += addnodes.desc_name(servicename, servicename) return sig class ServiceDocumenter(autodoc.ClassDocumenter): domain = 'wsme' objtype = 'service' directivetype = 'service' def add_directive_header(self, sig): super(ServiceDocumenter, self).add_directive_header(sig) # remove the :module: option that was added by ClassDocumenter if ':module:' in self.directive.result[-1]: self.directive.result.pop() def format_signature(self): return u'' def format_name(self): path = find_service_path(self.env, self.object) return '/' + '/'.join(path) class FunctionDirective(PyClassmember): name = 'function' objtype = 'function' def get_signature_prefix(self, sig): return 'function ' def document_function(funcdef, docstrings=None, protocols=['restjson']): """A helper function to complete a function documentation with return and parameter types""" # If the function doesn't have a docstring, add an empty list # so the default behaviors below work correctly. if not docstrings: docstrings = [[]] found_params = set() for si, docstring in enumerate(docstrings): for i, line in enumerate(docstring): m = field_re.match(line) if m and m.group('field') == 'param': found_params.add(m.group('name')) next_param_pos = (0, 0) for arg in funcdef.arguments: content = [ u':type %s: :wsme:type:`%s`' % ( arg.name, datatypename(arg.datatype)) ] if arg.name not in found_params: content.insert(0, u':param %s: ' % (arg.name)) pos = next_param_pos else: for si, docstring in enumerate(docstrings): for i, line in enumerate(docstring): m = field_re.match(line) if m and m.group('field') == 'param' \ and m.group('name') == arg.name: pos = (si, i + 1) break docstring = docstrings[pos[0]] docstring[pos[1]:pos[1]] = content next_param_pos = (pos[0], pos[1] + len(content)) if funcdef.return_type: content = [ u':rtype: %s' % datatypename(funcdef.return_type) ] pos = None for si, docstring in enumerate(docstrings): for i, line in enumerate(docstring): m = field_re.match(line) if m and m.group('field') == 'return': pos = (si, i + 1) break else: pos = next_param_pos docstring = docstrings[pos[0]] docstring[pos[1]:pos[1]] = content codesamples = [] if protocols: params = [] for arg in funcdef.arguments: params.append(( arg.name, arg.datatype, make_sample_object(arg.datatype) )) codesamples.extend([ u':%s:' % l_(u'Parameters samples'), u' .. cssclass:: toggle', u'' ]) for name, protocol in protocols: language, sample = protocol.encode_sample_params( params, format=True) codesamples.extend([ u' ' * 4 + name, u' .. code-block:: ' + language, u'', ]) codesamples.extend(( u' ' * 12 + line for line in six.text_type(sample).split('\n') )) if funcdef.return_type: codesamples.extend([ u':%s:' % l_(u'Return samples'), u' .. cssclass:: toggle', u'' ]) sample_obj = make_sample_object(funcdef.return_type) for name, protocol in protocols: language, sample = protocol.encode_sample_result( funcdef.return_type, sample_obj, format=True) codesamples.extend([ u' ' * 4 + name, u' .. code-block:: ' + language, u'', ]) codesamples.extend(( u' ' * 12 + line for line in six.text_type(sample).split('\n') )) docstrings[0:0] = [codesamples] return docstrings class FunctionDocumenter(autodoc.MethodDocumenter): domain = 'wsme' directivetype = 'function' objtype = 'function' priority = 1 option_spec = { 'path': directives.unchanged, 'method': directives.unchanged } @staticmethod def can_document_member(member, membername, isattr, parent): return (isinstance(parent, ServiceDocumenter) and wsme.api.iswsmefunction(member)) def import_object(self): ret = super(FunctionDocumenter, self).import_object() self.directivetype = 'function' self.wsme_fd = wsme.api.FunctionDefinition.get(self.object) self.retann = datatypename(self.wsme_fd.return_type) return ret def format_args(self): args = [arg.name for arg in self.wsme_fd.arguments] defaults = [ arg.default for arg in self.wsme_fd.arguments if not arg.mandatory ] return inspect.formatargspec(args, defaults=defaults) def get_doc(self, encoding=None): """Inject the type and param fields into the docstrings so that the user can add its own param fields to document the parameters""" docstrings = super(FunctionDocumenter, self).get_doc(encoding) protocols = get_protocols( self.options.protocols or self.env.app.config.wsme_protocols ) return document_function( self.wsme_fd, docstrings, protocols ) def add_content(self, more_content, no_docstring=False): super(FunctionDocumenter, self).add_content(more_content, no_docstring) def format_name(self): return self.wsme_fd.name def add_directive_header(self, sig): super(FunctionDocumenter, self).add_directive_header(sig) # remove the :module: option that was added by ClassDocumenter if ':module:' in self.directive.result[-1]: self.directive.result.pop() class WSMEDomain(Domain): name = 'wsme' label = 'WSME' object_types = { 'type': ObjType(l_('type'), 'type', 'obj'), 'service': ObjType(l_('service'), 'service', 'obj') } directives = { 'type': TypeDirective, 'attribute': AttributeDirective, 'service': ServiceDirective, 'root': RootDirective, 'function': FunctionDirective, } roles = { 'type': XRefRole() } initial_data = { 'types': {}, # fullname -> docname } def clear_doc(self, docname): keys = list(self.data['types'].keys()) for key in keys: value = self.data['types'][key] if value == docname: del self.data['types'][key] def resolve_xref(self, env, fromdocname, builder, type, target, node, contnode): if target not in self.data['types']: return None todocname = self.data['types'][target] return make_refnode( builder, fromdocname, todocname, target, contnode, target) def setup(app): app.add_domain(WSMEDomain) app.add_autodocumenter(TypeDocumenter) app.add_autodocumenter(AttributeDocumenter) app.add_autodocumenter(ServiceDocumenter) app.add_autodocumenter(FunctionDocumenter) app.add_config_value('wsme_root', None, 'env') app.add_config_value('wsme_webpath', '/', 'env') app.add_config_value('wsme_protocols', ['restjson', 'restxml'], 'env') app.add_javascript('toggle.js') app.add_stylesheet('toggle.css')