U \Sh4@sBdZddlmZddlZddlmZmZmZmZm Z m Z ddl m Z ddl mZddlmZmZddlmZdd lmZdd lm Z dd lmZmZmZdd lmZdd lmZddlm Z erddl!m"Z"e#dZ$e#dZ%dddddZ&e dZ'Gdddeee'Z(GdddeZ)GdddeZ*ddd d!d"Z+dS)#z(Handlers for additional ReST directives.) annotationsN) TYPE_CHECKINGAnyGenericListTypeVarcast)nodes)Node) directivesroles)addnodes)desc_signature)docutils)DocFieldTransformerField TypedField)SphinxDirective)nested_parse_with_titles) OptionSpec)Sphinxz\\\nz\\(.)strz int | None)argumentreturncCs,|dkr dSt|}|dkr$td|SdS)zS Check for an integer argument or None value; raise ``ValueError`` if not. Nrz(negative value; must be positive or zero)int ValueError)rvaluerM/root/rtd-docs/venv/lib/python3.8/site-packages/sphinx/directives/__init__.py optional_ints rObjDescTc@s eZdZUdZdZdZdZdZej ej ej dZ de d<gZ de d <d Z d e d <d e d<de d<iZde d<ddddZddddZd dddddZdd dddd d!Zddd"d#Zd$dd%d&d'Zddd(d)Zdd*d+d,d-Zdd d+d.d/Zd0dd1d2Zd S)3ObjectDescriptionz Directive to describe a class, function or similar object. Not used directly, but subclassed (in domain-specific directives) to add custom behavior. Tr)noindex noindexentrynocontentsentryr option_specz list[Field]doc_field_typesNz str | Nonedomainrobjtypezaddnodes.index indexnodezdict[str, tuple[Field, bool]]_doc_field_type_maprcCsf|jikr`i|_|jD]H}|jD]}|df|j|<q |jrtt|}|jD]}|df|j|<qJq|jS)NFT)r+r'namesZis_typedrrZ typenames)selffieldnameZ typed_fieldrrrget_field_type_mapGs     z$ObjectDescription.get_field_type_mapz list[str]cCs@td|jdd}|jjr.dd|DSdd|DSdS)z Retrieve the signatures to document from the directive arguments. By default, signatures are given as arguments, one per line. r cSsg|]}td|qS)z\1)strip_backslash_resubstrip.0linerrr ]sz4ObjectDescription.get_signatures..cSsg|] }|qSr)r6r7rrrr:_sN) nl_escape_rer5 argumentssplitconfigstrip_signature_backslash)r.linesrrrget_signaturesUsz ObjectDescription.get_signaturesrr )sigsignodercCstdS)a Parse the signature *sig* into individual nodes and append them to *signode*. If ValueError is raised, parsing is aborted and the whole *sig* is put into a single desc_name node. The return value should be a value that identifies the object. It is passed to :meth:`add_target_and_index()` unchanged, and otherwise only used to skip duplicates. N)r)r.rBrCrrrhandle_signatureas z"ObjectDescription.handle_signatureNone)r0rBrCrcCsdS)z Add cross-reference IDs and entries to self.indexnode, if applicable. *name* is whatever :meth:`handle_signature()` returned. Nr)r.r0rBrCrrradd_target_and_indexmsz&ObjectDescription.add_target_and_indexcCsdS)z Called before parsing content. Used to set information about the current directive context on the build environment. Nrr.rrrbefore_contentusz ObjectDescription.before_contentzaddnodes.desc_content) contentnodercCsdS)z Called after creating the content through nested parsing, but before the ``object-description-transform`` event is emitted, and before the info-fields are transformed. Can be used to manipulate the content. Nr)r.rIrrrtransform_content|sz#ObjectDescription.transform_contentcCsdS)z Called after parsing content. Used to reset information about the current directive context on the build environment. NrrGrrr after_contentszObjectDescription.after_contentztuple[str, ...])sig_nodercCsdS)a Returns a tuple of strings, one entry for each part of the object's hierarchy (e.g. ``('module', 'submodule', 'Class', 'method')``). The returned tuple is used to properly nest children within parents in the table of contents, and can also be used within the :py:meth:`_toc_entry_name` method. This method must not be used outwith table of contents generation. rrr.rLrrr_object_hierarchy_partss z)ObjectDescription._object_hierarchy_partscCsdS)a Returns the text of the table of contents entry for the object. This function is called once, in :py:meth:`run`, to set the name for the table of contents entry (a special attribute ``_toc_name`` is set on the object node, later used in ``environment.collectors.toctree.TocTreeCollector.process_doc().build_toc()`` when the table of contents entries are collected). To support table of contents entries for their objects, domains must override this method, also respecting the configuration setting ``toc_object_entries_show_parents``. Domains must also override :py:meth:`_object_hierarchy_parts`, with one (string) entry for each part of the object's hierarchy. The result of this method is set on the signature node, and can be accessed as ``sig_node['_toc_parts']`` for use within this method. The resulting tuple is also used to properly nest children within parents in the table of contents. An example implementations of this method is within the python domain (:meth:`!PyObject._toc_entry_name`). The python domain sets the ``_toc_parts`` attribute within the :py:meth:`handle_signature()` method. r2rrMrrr_toc_entry_namesz!ObjectDescription._toc_entry_name list[Node]c Cszd|jkr"|jdd\|_|_nd|j|_|_tjgd|_t}|jj |_ | \}}|dk rn|d8}|jj |||j|d<|j|d<|d<d |j k|d <}d |j k|d <d |j k|d <|jr|d  |j|d  |dg|_|}|D]}t|d}||| |zNz|||}Wn8tk rp||t||7}YWqYnXW5|jjjjr|||d <|||d<nd|d <d|d<X||jkr|j ||s||||qt} | | |jr|jd|jjd<|t |j|j!| |j"|#| |jj$d|j|j| t%|&| d|jjd<|'|j|gS)a 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 :r"r2)entriesNr(r)Zdesctyper#r$r%classesZ _toc_partsZ _toc_namerrobjectobject-description-transform)(r0r=r(r)r indexr*descstateZdocumentZget_source_infoZ note_sourceoptionsappendr-rArZset_source_infoenvappr>Ztoc_object_entriesrNrOrDrclearZ desc_namerFZ desc_content temp_datarHrcontentZcontent_offsetrJemitrZ transform_allrK) r.nodesourcer9r#Z signaturesrBrCr0rIrrrrunsn              zObjectDescription.run)__name__ __module__ __qualname____doc__ has_contentrequired_argumentsoptional_argumentsfinal_argument_whitespacer flagr&__annotations__r'r(r+r1rArDrFrHrJrKrNrOrcrrrrr!-s0        r!c@s&eZdZdZdZdZddddZdS) DefaultRolezK Set the default interpreted text role. Overridden from docutils. r"FrPr,cCs|jstdgS|jd}t||jj|j|jj \}}|rZt d|||j j d<n8t |j|j}|jj }|jd|||jd}||g7}ttt j|S)Nr2rZ default_rolez#Unknown interpreted text role "%s".)r9)r<rZunregister_roler roleZ state_machinelanguagelinenorXreporterZ register_roler[r^r literal_blockZ block_texterrorrrr )r.Z role_nameromessagesrsrrrtrrrrcs&      zDefaultRole.runN)rdrerfrgrjrkrcrrrrrnsrnc@s<eZdZUdZdZdZdZdZiZde d<ddd d Z d S) DefaultDomainzH Directive to (re-)set the default domain for this source file. Fr"rrr&rPr,cCs(|jd}|jj||jjd<gS)NrZdefault_domain)r<lowerr[domainsgetr^)r.Z domain_namerrrrc;szDefaultDomain.runN) rdrerfrgrhrirjrkr&rmrcrrrrrv0s  rvrzdict[str, Any])r\rcCsT|dddtdttdttdttdt|dd d d d S) Nr?Fr[z default-rolezdefault-domainZdescriberTrUbuiltinT)versionZparallel_read_safeZparallel_write_safe)Zadd_config_valuer Zregister_directivernrvr!Z add_event)r\rrrsetupGs     r|),rg __future__rretypingrrrrrrrr Zdocutils.nodesr Zdocutils.parsers.rstr r Zsphinxr Zsphinx.addnodesrZ sphinx.utilZsphinx.util.docfieldsrrrZsphinx.util.docutilsrZsphinx.util.nodesrZsphinx.util.typingrZsphinx.applicationrcompiler;r4rr r!rnrvr|rrrrs0              h