# -*- coding: utf-8 -*-""" sphinx.domains ~~~~~~~~~~~~~~ Support for domains, which are groupings of description directives and roles describing e.g. constructs of one programming language. :copyright: Copyright 2007-2010 by the Sphinx team, see AUTHORS. :license: BSD, see LICENSE for details."""fromsphinx.errorsimportSphinxErrorfromsphinx.localeimport_classObjType(object):""" An ObjType is the description for a type of object that a domain can document. In the object_types attribute of Domain subclasses, object type names are mapped to instances of this class. Constructor arguments: - *lname*: localized name of the type (do not include domain name) - *roles*: all the roles that can refer to an object of this type - *attrs*: object attributes -- currently only "searchprio" is known, which defines the object's priority in the full-text search index, see :meth:`Domain.get_objects()`. """known_attrs={'searchprio':1,}def__init__(self,lname,*roles,**attrs):self.lname=lnameself.roles=rolesself.attrs=self.known_attrs.copy()self.attrs.update(attrs)classIndex(object):""" An Index is the description for a domain-specific index. To add an index to a domain, subclass Index, overriding the three name attributes: * `name` is an identifier used for generating file names. * `localname` is the section title for the index. * `shortname` is a short name for the index, for use in the relation bar in HTML output. Can be empty to disable entries in the relation bar. and providing a :meth:`generate()` method. Then, add the index class to your domain's `indices` list. Extensions can add indices to existing domains using :meth:`~sphinx.application.Sphinx.add_index_to_domain()`. """name=Nonelocalname=Noneshortname=Nonedef__init__(self,domain):ifself.nameisNoneorself.localnameisNone:raiseSphinxError('Index subclass %s has no valid name or localname'%self.__class__.__name__)self.domain=domaindefgenerate(self,docnames=None):"""Return entries for the index given by *name*. If *docnames* is given, restrict to entries referring to these docnames. The return value is a tuple of ``(content, collapse)``, where *collapse* is a boolean that determines if sub-entries should start collapsed (for output formats that support collapsing sub-entries). *content* is a sequence of ``(letter, entries)`` tuples, where *letter* is the "heading" for the given *entries*, usually the starting letter. *entries* is a sequence of single entries, where a single entry is a sequence ``[name, subtype, docname, anchor, extra, qualifier, descr]``. The items in this sequence have the following meaning: - `name` -- the name of the index entry to be displayed - `subtype` -- sub-entry related type: 0 -- normal entry 1 -- entry with sub-entries 2 -- sub-entry - `docname` -- docname where the entry is located - `anchor` -- anchor for the entry within `docname` - `extra` -- extra info for the entry - `qualifier` -- qualifier for the description - `descr` -- description for the entry Qualifier and description are not rendered e.g. in LaTeX output. """return[]classDomain(object):""" A Domain is meant to be a group of "object" description directives for objects of a similar nature, and corresponding roles to create references to them. Examples would be Python modules, classes, functions etc., elements of a templating language, Sphinx roles and directives, etc. Each domain has a separate storage for information about existing objects and how to reference them in `self.data`, which must be a dictionary. It also must implement several functions that expose the object information in a uniform way to parts of Sphinx that allow the user to reference or search for objects in a domain-agnostic way. About `self.data`: since all object and cross-referencing information is stored on a BuildEnvironment instance, the `domain.data` object is also stored in the `env.domaindata` dict under the key `domain.name`. Before the build process starts, every active domain is instantiated and given the environment object; the `domaindata` dict must then either be nonexistent or a dictionary whose 'version' key is equal to the domain class' :attr:`data_version` attribute. Otherwise, `IOError` is raised and the pickled environment is discarded. """#: domain name: should be short, but uniquename=''#: domain label: longer, more descriptive (used in messages)label=''#: type (usually directive) name -> ObjType instanceobject_types={}#: directive name -> directive classdirectives={}#: role name -> role callableroles={}#: a list of Index subclassesindices=[]#: data value for a fresh environmentinitial_data={}#: data version, bump this when the format of `self.data` changesdata_version=0def__init__(self,env):self.env=envifself.namenotinenv.domaindata:assertisinstance(self.initial_data,dict)new_data=self.initial_data.copy()new_data['version']=self.data_versionself.data=env.domaindata[self.name]=new_dataelse:self.data=env.domaindata[self.name]ifself.data['version']!=self.data_version:raiseIOError('data of %r domain out of date'%self.label)self._role_cache={}self._directive_cache={}self._role2type={}forname,objinself.object_types.iteritems():forrolenameinobj.roles:self._role2type.setdefault(rolename,[]).append(name)self.objtypes_for_role=self._role2type.getdefrole(self,name):"""Return a role adapter function that always gives the registered role its full name ('domain:name') as the first argument. """ifnameinself._role_cache:returnself._role_cache[name]ifnamenotinself.roles:returnNonefullname='%s:%s'%(self.name,name)defrole_adapter(typ,rawtext,text,lineno,inliner,options={},content=[]):returnself.roles[name](fullname,rawtext,text,lineno,inliner,options,content)self._role_cache[name]=role_adapterreturnrole_adapterdefdirective(self,name):"""Return a directive adapter class that always gives the registered directive its full name ('domain:name') as ``self.name``. """ifnameinself._directive_cache:returnself._directive_cache[name]ifnamenotinself.directives:returnNonefullname='%s:%s'%(self.name,name)BaseDirective=self.directives[name]classDirectiveAdapter(BaseDirective):defrun(self):self.name=fullnamereturnBaseDirective.run(self)self._directive_cache[name]=DirectiveAdapterreturnDirectiveAdapter# methods that should be overwrittendefclear_doc(self,docname):"""Remove traces of a document in the domain-specific inventories."""passdefprocess_doc(self,env,docname,document):"""Process a document after it is read by the environment."""passdefresolve_xref(self,env,fromdocname,builder,typ,target,node,contnode):"""Resolve the pending_xref *node* with the given *typ* and *target*. This method should return a new node, to replace the xref node, containing the *contnode* which is the markup content of the cross-reference. If no resolution can be found, None can be returned; the xref node will then given to the 'missing-reference' event, and if that yields no resolution, replaced by *contnode*. The method can also raise :exc:`sphinx.environment.NoUri` to suppress the 'missing-reference' event being emitted. """passdefget_objects(self):"""Return an iterable of "object descriptions", which are tuples with five items: * `name` -- fully qualified name * `dispname` -- name to display when searching/linking * `type` -- object type, a key in ``self.object_types`` * `docname` -- the document where it is to be found * `anchor` -- the anchor name for the object * `priority` -- how "important" the object is (determines placement in search results) - 1: default priority (placed before full-text matches) - 0: object is important (placed before default-priority objects) - 2: object is unimportant (placed after full-text matches) - -1: object should not show up in search at all """return[]defget_type_name(self,type,primary=False):"""Return full name for given ObjType."""ifprimary:returntype.lnamereturn_('%s%s')%(self.label,type.lname)fromsphinx.domains.cimportCDomainfromsphinx.domains.cppimportCPPDomainfromsphinx.domains.stdimportStandardDomainfromsphinx.domains.pythonimportPythonDomainfromsphinx.domains.javascriptimportJavaScriptDomainfromsphinx.domains.rstimportReSTDomainfromsphinx.domains.valaimportValaDomainBUILTIN_DOMAINS={'std':StandardDomain,'py':PythonDomain,'c':CDomain,'cpp':CPPDomain,'js':JavaScriptDomain,'rst':ReSTDomain,'vala':ValaDomain,}