def run(self): document = self.state.document env = document.settings.env docname = env.docname if ':' in self.name: self.domain, self.objtype = self.name.split(':', 1) else: self.domain, self.objtype = 'py', self.name key = self.find_key(self.content.parent) targetnode = nodes.target('', '', ids=[key]) key_elem = keynode(key) # Separating argument and content causes two <dd>-s to be generated in # the same <dl> doc = addnodes.desc_content() update_attrs(doc, self) txt = '\n'.join(self.arguments) self.before_content() details = keydoc(self.state, self.content) update_attrs(details, self) DocFieldTransformer(self).transform_all(details) self.after_content() doc += nodes.paragraph(txt, txt) doc += details import os source_line = self.lineno source, _ = self.state_machine.get_source_and_line(source_line) src_file, src_other = source.split(':', 1) source_file = os.path.basename(src_file) doc_entry = ibkey(self, key, key_elem, doc) #doc_entry = make_admonition(dummy, self.name, 'Alma', self.options, self.content, self.lineno, self.content_offset, self.block_text, self.state, self.state_machine)[0] catalog_entry = iblist_entry(self, env, docname, src_other, source_file, source_line, key, key_elem, doc) set_source_info(self, doc_entry) set_source_info(self, catalog_entry) env.resolve_references(doc_entry, docname, env.app.builder) env.resolve_references(catalog_entry, docname, env.app.builder) if not hasattr(env, 'ibkey_all_ibkeys'): env.ibkey_all_ibkeys = dict() env.ibkey_all_ibkeys[key] = dict(docname=docname, catalog_entry=catalog_entry) # - super.run() doesnt't kill the structure, it works fine # - returning both superrun and doc_entry does (in any order) # - The todo in the method docstring is rendered outside the # method's documentation (?!) return [doc_entry] #[targetnode, doc_entry]
def docstring(self, node, scope): docstringlines = node.docstring.split("\n") self.env.app.emit('autodoc-process-docstring', 'class', node["ids"][0], node, {}, docstringlines) content = ViewList(docstringlines) docstringnode = nodes.paragraph() self.state.nested_parse(content, self.content_offset, docstringnode) DocFieldTransformer(self).transform_all(docstringnode) node.insert(0, docstringnode)
def run(self): self.env = env = self.state.document.settings.env # normalize whitespace in fullname like XRefRole does fullname = ws_re.sub(' ', self.arguments[0].strip()) targetname = '%s-%s' % (self.ref_type, fullname) # keep the target; this may be used to generate a BBIndex later targets = env.domaindata['bb']['targets'].setdefault(self.ref_type, {}) targets[fullname] = env.docname, targetname # make up the descriptor: a target and potentially an index descriptor node = nodes.target('', '', ids=[targetname]) ret = [node] # add the target to the document self.state.document.note_explicit_target(node) # append the index node if necessary entries = [] for tpl in self.indextemplates: colon = tpl.find(':') if colon != -1: indextype = tpl[:colon].strip() indexentry = tpl[colon + 1:].strip() % (fullname, ) else: indextype = 'single' indexentry = tpl % (fullname, ) entries.append( (indextype, indexentry, targetname, targetname, None)) if entries: inode = addnodes.index(entries=entries) ret.insert(0, inode) # if the node has content, set up a signature and parse the content if self.has_content: descnode = addnodes.desc() descnode['domain'] = 'bb' descnode['objtype'] = self.ref_type descnode['noindex'] = True signode = addnodes.desc_signature(fullname, '') if self.name_annotation: annotation = "%s " % self.name_annotation signode += addnodes.desc_annotation(annotation, annotation) signode += addnodes.desc_name(fullname, fullname) descnode += signode contentnode = addnodes.desc_content() self.state.nested_parse(self.content, 0, contentnode) DocFieldTransformer(self).transform_all(contentnode) descnode += contentnode ret.append(descnode) return ret
def run(self) -> List[nodes.Node]: # noqa: D102 if ':' in self.name: self.domain, self.objtype = self.name.split(':', 1) else: self.domain, self.objtype = '', self.name self.indexnode = addnodes.index(entries=[]) node = OptionDesc() node.document = self.state.document node["domain"] = self.domain # 'desctype' is a backwards compatible attribute node["objtype"] = node["desctype"] = self.objtype node["noindex"] = noindex = ("noindex" in self.options) if self.domain: node["classes"].append(self.domain) self.names: List[Any] = [] signatures = self.get_signatures() for i, sig in enumerate(signatures): # add a signature node for each signature in the current unit # and add a reference target for it signode = addnodes.desc_signature(sig, '') self.set_source_info(signode) node.append(signode) try: # name can also be a tuple, e.g. (classname, objname); # this is strictly domain-specific (i.e. no assumptions may # be made in this base class) name = self.handle_signature(sig, signode) except ValueError: # signature parsing failed signode.clear() signode += addnodes.desc_name(sig, sig) continue # we don't want an index entry here if name not in self.names: self.names.append(name) if not noindex: # only add target and index entry if this is the first # description of the object with this name in this desc block self.add_target_and_index(name, sig, signode) contentnode = addnodes.desc_content() node.append(contentnode) if self.names: # needed for association of version{added,changed} directives self.env.temp_data["object"] = self.names[0] self.before_content() self.state.nested_parse(self.content, self.content_offset, contentnode) self.transform_content(contentnode) self.env.app.emit("object-description-transform", self.domain, self.objtype, contentnode) DocFieldTransformer(self).transform_all(contentnode) self.env.temp_data["object"] = None self.after_content() return [self.indexnode, node]
def run(self): if ':' in self.name: self.domain, self.objtype = self.name.split(':', 1) else: self.domain, self.objtype = '', self.name self.indexnode = addnodes.index(entries=[]) node = addnodes.desc() node.document = self.state.document node['domain'] = self.domain node['classes'].append('csharp') node['objtype'] = node['desctype'] = self.objtype node['noindex'] = noindex = ('noindex' in self.options) self.names = [] signatures = self.get_signatures() for i, sig in enumerate(signatures): beforesignode = CSNodes.EmptyNode() node.append(beforesignode) signode = addnodes.desc_signature(sig, '') signode['first'] = False node.append(signode) self.before_sig(beforesignode) try: name = self.handle_signature(sig, signode) except ValueError: signode.clear() signode += addnodes.desc_name(sig, sig) continue if name not in self.names: self.names.append(name) if not noindex: self.add_target_and_index(name, sig, signode) aftersignode = CSNodes.EmptyNode() node.append(aftersignode) self.after_sig(aftersignode) contentnode = addnodes.desc_content() node.append(contentnode) self.before_content_node(contentnode) if self.names: self.env.temp_data['object'] = self.names[0] self.before_content() self.state.nested_parse(self.content, self.content_offset, contentnode) self.after_content_node(contentnode) DocFieldTransformer(self).transform_all(contentnode) self.env.temp_data['object'] = None self.after_content() return [self.indexnode, node]
def run(self): if ':' in self.name: self.domain, self.objtype = self.name.split(':', 1) else: self.domain, self.objtype = '', self.name self.env = self.state.document.settings.env modelnode = self.parse_arguments() scope = self.env.ref_context.get('jl:scope', []) docname = self.env.docname dictionary = self.env.domaindata['jl'][self.objtype] modelnode["ids"] = [modelnode.uid(scope)] modelnode.register(docname, scope, dictionary) self.parse_content(modelnode) DocFieldTransformer(self).transform_all(modelnode) return [modelnode]
def _render_service(self, service): service_id = "service-%d" % self.env.new_serialno('service') service_node = nodes.section(ids=[service_id]) title = '%s service at %s' % (service.name.title(), service.path) service_node += nodes.title(text=title) if service.description is not None: service_node += rst2node(trim(service.description)) for method, view, args in service.definitions: if method == 'HEAD': #Skip head - this is essentially duplicating the get docs. continue method_id = '%s-%s' % (service_id, method) method_node = nodes.section(ids=[method_id]) method_node += nodes.title(text=method) if is_string(view): if 'klass' in args: ob = args['klass'] view_ = getattr(ob, view.lower()) docstring = trim(view_.__doc__ or "") + '\n' else: docstring = trim(view.__doc__ or "") + '\n' if 'schema' in args: schema = args['schema'] attrs_node = nodes.inline() for location in ('header', 'querystring', 'body'): attributes = schema.get_attributes(location=location) if attributes: attrs_node += nodes.inline(text='values in the %s' % location) location_attrs = nodes.bullet_list() for attr in attributes: temp = nodes.list_item() desc = "%s : " % attr.name # Get attribute data-type if hasattr(attr, 'type'): attr_type = attr.type elif hasattr(attr, 'typ'): attr_type = attr.typ.__class__.__name__ desc += " %s, " % attr_type if attr.required: desc += "required " else: desc += "optional " temp += nodes.inline(text=desc) location_attrs += temp attrs_node += location_attrs method_node += attrs_node for validator in args.get('validators', ()): if validator.__doc__ is not None: docstring += trim(validator.__doc__) if 'accept' in args: accept = to_list(args['accept']) if callable(accept): if accept.__doc__ is not None: docstring += accept.__doc__.strip() else: accept_node = nodes.strong(text='Accepted content types:') node_accept_list = nodes.bullet_list() accept_node += node_accept_list for item in accept: temp = nodes.list_item() temp += nodes.inline(text=item) node_accept_list += temp method_node += accept_node node = rst2node(docstring) DocFieldTransformer(self).transform_all(node) if node is not None: method_node += node renderer = args['renderer'] if renderer == 'simplejson': renderer = 'json' response = nodes.paragraph() response += nodes.strong(text='Response: %s' % renderer) method_node += response service_node += method_node return service_node
def run(self): # type: () -> List[nodes.Node] """ Main directive entry function, called by docutils upon encountering the directive. This directive is meant to be quite easily subclassable, so it delegates to several additional methods. What it does: * find out if called as a domain-specific directive, set self.domain * create a `desc` node to fit all description inside * parse standard options, currently `noindex` * create an index node if needed as self.indexnode * parse all given signatures (as returned by self.get_signatures()) using self.handle_signature(), which should either return a name or raise ValueError * add index entries using self.add_target_and_index() * parse the content and handle doc fields in it """ if ':' in self.name: self.domain, self.objtype = self.name.split(':', 1) else: self.domain, self.objtype = '', self.name self.indexnode = addnodes.index(entries=[]) node = addnodes.desc() node.document = self.state.document node['domain'] = self.domain # 'desctype' is a backwards compatible attribute node['objtype'] = node['desctype'] = self.objtype node['noindex'] = noindex = ('noindex' in self.options) self.names = [] # type: List[unicode] signatures = self.get_signatures() for i, sig in enumerate(signatures): # add a signature node for each signature in the current unit # and add a reference target for it signode = addnodes.desc_signature(sig, '') signode['first'] = False node.append(signode) try: # name can also be a tuple, e.g. (classname, objname); # this is strictly domain-specific (i.e. no assumptions may # be made in this base class) name = self.handle_signature(sig, signode) except ValueError: # signature parsing failed signode.clear() signode += addnodes.desc_name(sig, sig) continue # we don't want an index entry here if name not in self.names: self.names.append(name) if not noindex: # only add target and index entry if this is the first # description of the object with this name in this desc block self.add_target_and_index(name, sig, signode) contentnode = addnodes.desc_content() node.append(contentnode) if self.names: # needed for association of version{added,changed} directives self.env.temp_data['object'] = self.names[0] self.before_content() self.state.nested_parse(self.content, self.content_offset, contentnode) DocFieldTransformer(self).transform_all(contentnode) self.env.temp_data['object'] = None self.after_content() return [self.indexnode, node]
def _render_service(self, path, service, methods): env = self.state.document.settings.env service_id = "service-%d" % env.new_serialno('service') service_node = nodes.section(ids=[service_id]) service_node += nodes.title(text='Service at %s' % service.route_name) if service.description is not None: service_node += rst2node(trim(service.description)) for method, info in methods.items(): method_id = '%s-%s' % (service_id, method) method_node = nodes.section(ids=[method_id]) method_node += nodes.title(text=method) if 'attr' in info: docstring = getattr(info['func'], info['attr']).__doc__ or "" else: docstring = info['func'].__doc__ or "" docstring = trim(docstring) + '\n' if method in service.schemas: schema = service.schemas[method] attrs_node = nodes.inline() for location in ('headers', 'querystring', 'body'): attributes = schema.get_attributes(location=location) if attributes: attrs_node += nodes.inline(text='values in the %s' % location) location_attrs = nodes.bullet_list() for attr in attributes: temp = nodes.list_item() desc = "%s : " % attr.name if hasattr(attr, 'type'): desc += " %s, " % attr.type if attr.required: desc += "required " else: desc += "optional " temp += nodes.inline(text=desc) location_attrs += temp attrs_node += location_attrs method_node += attrs_node if 'validators' in info: for validator in info['validators']: if validator.__doc__ is not None: if docstring is not None: doc = trim(validator.__doc__) docstring += '\n' + doc if 'accept' in info: accept = info['accept'] if callable(accept): if accept.__doc__ is not None: docstring += accept.__doc__.strip() else: accept = to_list(accept) accept_node = nodes.strong(text='Accepted content types:') node_accept_list = nodes.bullet_list() accept_node += node_accept_list for item in accept: temp = nodes.list_item() temp += nodes.inline(text=item) node_accept_list += temp method_node += accept_node node = rst2node(docstring) DocFieldTransformer(self).transform_all(node) if node is not None: method_node += node renderer = info['renderer'] if renderer == 'simplejson': renderer = 'json' response = nodes.paragraph() response += nodes.strong(text='Response: %s' % renderer) method_node += response service_node += method_node return service_node
def _render_service(self, service): service_id = "service-%d" % self.env.new_serialno('service') service_node = nodes.section(ids=[service_id]) title = '%s service at %s' % (service.name.title(), service.path) service_node += nodes.title(text=title) if service.description is not None: service_node += rst2node(trim(service.description), self.env) for method, view, args in service.definitions: if method == 'HEAD': # Skip head - this is essentially duplicating the get docs. continue method_id = '%s-%s' % (service_id, method) method_node = nodes.section(ids=[method_id]) method_node += nodes.title(text=method) docstring = self._resolve_obj_to_docstring(view, args) if 'schema' in args: schema = args['schema'] attrs_node = nodes.inline() for location in ('header', 'querystring', 'body'): attributes = self._get_attributes(schema, location=location) if attributes: attrs_node += nodes.inline( text='values in the %s' % location) location_attrs = nodes.bullet_list() for attr in attributes: temp = nodes.list_item() # Get attribute data-type if hasattr(attr, 'type'): attr_type = attr.type elif hasattr(attr, 'typ'): attr_type = attr.typ.__class__.__name__ else: attr_type = None temp += nodes.strong(text=attr.name) if attr_type is not None: temp += nodes.inline(text=' (%s)' % attr_type) if not attr.required or attr.description: temp += nodes.inline(text=' - ') if not attr.required: if attr.missing is not None: default = json.dumps(attr.missing) temp += nodes.inline( text='(default: %s) ' % default) else: temp += nodes.inline( text='(optional) ') if attr.description: temp += nodes.inline(text=attr.description) location_attrs += temp attrs_node += location_attrs method_node += attrs_node for validator in args.get('validators', ()): docstring += self._resolve_obj_to_docstring(validator, args) if 'accept' in args: accept = to_list(args['accept']) if callable(accept): if accept.__doc__ is not None: docstring += accept.__doc__.strip() else: accept_node = nodes.strong(text='Accepted content types:') node_accept_list = nodes.bullet_list() accept_node += node_accept_list for item in accept: temp = nodes.list_item() temp += nodes.inline(text=item) node_accept_list += temp method_node += accept_node node = rst2node(docstring, self.env) DocFieldTransformer(self).transform_all(node) if node is not None: method_node += node renderer = args['renderer'] if renderer == 'simplejson': renderer = 'json' response = nodes.paragraph() response += nodes.strong(text='Response: %s' % renderer) method_node += response service_node += method_node return service_node
def run(self) -> List[Node]: """ Main directive entry function, called by docutils upon encountering the directive. This directive is meant to be quite easily subclassable, so it delegates to several additional methods. What it does: * find out if called as a domain-specific directive, set self.domain * create a `desc` node to fit all description inside * parse standard options, currently `noindex` * create an index node if needed as self.indexnode * parse all given signatures (as returned by self.get_signatures()) using self.handle_signature(), which should either return a name or raise ValueError * add index entries using self.add_target_and_index() * parse the content and handle doc fields in it """ if ":" in self.name: self.domain, self.objtype = self.name.split(":", 1) else: self.domain, self.objtype = "", self.name self.indexnode = addnodes.index(entries=[]) nest_depth = "nested-%d" % self.get_nesting_depth() node = nodes.admonition(classes=["toggle", self.objtype, nest_depth]) node.document = self.state.document node["domain"] = self.domain # 'desctype' is a backwards compatible attribute node["objtype"] = node["desctype"] = self.objtype node["noindex"] = noindex = "noindex" in self.options if self.domain: node["classes"].append(self.domain) self.names = [] # type: List[Any] signatures = self.get_signatures() assert len(signatures) == 1, "only assuming 1 signature can be given" for i, sig in enumerate(signatures): # add a signature node for each signature in the current unit # and add a reference target for it signode = nodes.title(sig, "") self.set_source_info(signode) node.append(signode) try: # name can also be a tuple, e.g. (classname, objname); # this is strictly domain-specific (i.e. no assumptions may # be made in this base class) name = self.handle_signature(sig, signode) except ValueError: # signature parsing failed signode.clear() signode += addnodes.desc_name(sig, sig) continue # we don't want an index entry here if name not in self.names: self.names.append(name) if not noindex: # only add target and index entry if this is the first # description of the object with this name in this desc # block self.add_target_and_index(name, sig, signode) contentnode = nodes.paragraph() node.append(contentnode) if self.names: # needed for association of version{added,changed} directives self.env.temp_data["object"] = self.names[0] self.before_content() self.state.nested_parse(self.content, self.content_offset, contentnode) self.transform_content(contentnode) self.env.app.emit("object-description-transform", self.domain, self.objtype, contentnode) DocFieldTransformer(self).transform_all(contentnode) self.env.temp_data["object"] = None self.after_content() # Do this here so `become_parent` hasn't taken effect too early self.define_graph(signatures[0]) return [self.indexnode, node]
def _render_service(self, service): service_id = "service-%d" % self.env.new_serialno("service") service_node = nodes.section(ids=[service_id]) title = "%s service at %s" % (service.name.title(), service.path) service_node += nodes.title(text=title) if service.description is not None: service_node += rst2node(trim(service.description), self.env) for method, view, args in service.definitions: if method == "HEAD": # Skip head - this is essentially duplicating the get docs. continue method_id = "%s-%s" % (service_id, method) method_node = nodes.section(ids=[method_id]) method_node += nodes.title(text=method) docstring = self._resolve_obj_to_docstring(view, args) if "schema" in args: schema = args["schema"] attrs_node = nodes.inline() for location in ("header", "querystring", "body"): attributes = self._get_attributes(schema, location=location) if attributes: attrs_node += nodes.inline(text="values in the %s" % location) location_attrs = nodes.bullet_list() for attr in attributes: location_attrs += self._render_element_recursively( attr) attrs_node += location_attrs method_node += attrs_node for validator in args.get("validators", ()): docstring += self._resolve_obj_to_docstring(validator, args) if "accept" in args: accept = to_list(args["accept"]) if callable(accept): if accept.__doc__ is not None: docstring += accept.__doc__.strip() else: accept_node = nodes.strong(text="Accepted content types:") node_accept_list = nodes.bullet_list() accept_node += node_accept_list for item in accept: temp = nodes.list_item() temp += nodes.inline(text=item) node_accept_list += temp method_node += accept_node node = rst2node(docstring, self.env) DocFieldTransformer(self).transform_all(node) if node is not None: method_node += node renderer = args["renderer"] if renderer == "simplejson": renderer = "json" response = nodes.paragraph() response += nodes.strong(text="Response: %s" % renderer) method_node += response service_node += method_node return service_node