o Nib@sUdZddlmZddlZddlZddlmZddlmZddl m Z ddlm Z ddl m Z m Z mZmZddlZdd lmZdd lmZdd lmZmZmZdd lmZdd lmZmZmZddlmZm Z ddl!m"Z"ddl#m$Z$m%Z%ddl&m'Z'ddl(m)Z)e'*e+Z,e-dZ.e rddlm/Z/m0Z0ddl1m2Z2ddl3m4Z4ddl5m6Z6m7Z7m8Z8ddl9m:Z:ddl;mZ>ddl?m@Z@eAZBdeCd<edjd d!ZDdkd%d&ZEdld*d+ZFdkd,d-ZGdmd0d1ZHdnd2d3ZIdod6d7ZJdpd8d9ZKdpd:d;ZLedjdd?ZNedqdBdCZOedrdqdDdEZPGdFdGdGZQGdHdIdIeRZSGdJdKdKeQZTGdLdMdMZUGdNdOdOeZVGdPdQdQeZWedsdVdWZXGdXdYdYeZYGdZd[d[eZZGd\d]d]Z[Gd^d_d_e[Z\Gd`dadaej]Z^dbeCdc<drdtdhdiZ_dS)uzUtility functions for docutils.) annotationsN)Sequence)contextmanager)copy)path)IO TYPE_CHECKINGAnycast)nodes) FileOutput) Directive directivesroles)Inliner)State StateMachine StringList)Reporterunescape) SphinxError)___)logging)nested_parse_to_nodesz>^(.+?:(?:\d+)?): \((DEBUG|INFO|WARNING|ERROR|SEVERE)/(\d+)?\) )CallableIterator) ModuleType)Values)ElementNodesystem_message)Builder)Config)BuildEnvironment) RoleFunctionzset[type[Element]]additional_nodesreturnIterator[None]c cs~z&ttj}ttj}dVW|t_|t_ttD] }t|t|qdS|t_|t_ttD] }t|t|q2w)z"Create namespace for reST parsers.N) rr _directivesr_roleslistr&unregister_nodediscard)r)r*noder/H/home/ubuntu/.local/lib/python3.10/site-packages/sphinx/util/docutils.pydocutils_namespace/s"      r1namestrboolcC |tjvS)z1Check the *name* directive is already registered.)rr)r2r/r/r0is_directive_registered@ r7 directivetype[Directive]NonecCt||dS)zRegister a directive to docutils. This modifies global state of docutils. So it is better to use this inside ``docutils_namespace()`` to prevent side-effects. N)rregister_directive)r2r9r/r/r0r=Er=cCr5)z,Check the *name* role is already registered.)rr*r6r/r/r0is_role_registeredNr8r?roler%cCr<)zRegister a role to docutils. This modifies global state of docutils. So it is better to use this inside ``docutils_namespace()`` to prevent side-effects. N)rregister_local_role)r2r@r/r/r0 register_roleSr>rBcCstj|ddS)z Unregister a role from docutils.N)rr*popr6r/r/r0unregister_role\rDr. type[Element]cCsttjd|jS)z'Check the *node* is already registered.visit_)hasattrr GenericNodeVisitor__name__r.r/r/r0is_node_registeredarErLcCs2ttjd|jst|jgt|dSdS)zRegister a node to docutils. This modifies global state of some visitors. So it is better to use this inside ``docutils_namespace()`` to prevent side-effects. rGN)rHr rIrJ_add_node_class_namesr&addrKr/r/r0 register_nodefsrOcCsbttjd|jr/ttjd|jttjd|jttjd|jttjd|jdSdS)zaUnregister a node from docutils. This is inverse of ``nodes._add_nodes_class_names()``. rGdepart_N)rHr rIrJdelattrSparseNodeVisitorrKr/r/r0r,qs r,c#sHddlm d d fd d }z|tj_dVWtj_dStj_w)zPatch docutils.languages.get_language() temporarily. This ignores the second argument ``reporter`` to suppress warnings. refs: https://github.com/sphinx-doc/sphinx/issues/3788 r get_languageN language_coder3reporterReporter | Noner'r c|SNr/rUrVrSr/r0patched_get_languagez2patched_get_language..patched_get_languagerYrUr3rVrWr'r )docutils.languagesrTdocutils languagesr[r/rSr0r[}s r[c#sTddlm d d fd d }z|tjjj_dVWtjjj_dStjjj_w)a^Patch docutils.parsers.rst.languages.get_language(). Starting from docutils 0.17, get_language() in ``rst.languages`` also has a reporter, which needs to be disabled temporarily. This should also work for old versions of docutils, because reporter is none by default. refs: https://github.com/sphinx-doc/sphinx/issues/10179 rrSNrUr3rVrWr'r crXrYr/rZrSr/r0r[r\z6patched_rst_get_language..patched_get_languagerYr])docutils.parsers.rst.languagesrTr_parsersrstr`rar/rSr0patched_rst_get_languages  reconfdir str | Nonec csz-tjdd}|rtt|dtjd<dVW|dur(tjdddS|tjd<dS|dur;tjddw|tjd<w)z?Let docutils know the location of ``docutils.conf`` for Sphinx.DOCUTILSCONFIGNz docutils.conf)osenvirongetrjoinabspathrC)rfdocutilsconfigr/r/r0using_user_docutils_confs  roc cst;tt| dVWdn1swYWdn1s*wYWddSWddS1sBwYdS)zPatch to docutils temporarily.N)r[rero)rfr/r/r0patch_docutilssPrpc@sVeZdZdZd&ddZd&ddZd'ddZd&ddZd&ddZd(ddZ d)d#d$Z d%S)*CustomReSTDispatcherzCustom reST's mark-up dispatcher. This replaces docutils's directives and roles dispatch mechanism for reST parser by original one temporarily. r'r;cCsdd|_dd|_dS)NcWdgfSrYr/argsr/r/r0z/CustomReSTDispatcher.__init__..cWrrrYr/rsr/r/r0rurv)directive_func roles_funcselfr/r/r0__init__s zCustomReSTDispatcher.__init__cC |dSrY)enableryr/r/r0 __enter__s zCustomReSTDispatcher.__enter__exc_typetype[Exception] exc_value Exception tracebackr cCr|rY)disable)rzrrrr/r/r0__exit__s zCustomReSTDispatcher.__exit__cCs$tj|_tj|_|jt_|jt_dSrY)rr9rwrr@ role_funcryr/r/r0r}s zCustomReSTDispatcher.enablecCs|jt_|jt_dSrY)rwrr9rrr@ryr/r/r0rs zCustomReSTDispatcher.disabledirective_namer3language_modulerdocumentnodes.document3tuple[type[Directive] | None, list[system_message]]cCs||||SrY)rwrzrrrr/r/r0r9szCustomReSTDispatcher.directive role_namelinenointrVr)tuple[RoleFunction, list[system_message]]cCs|||||SrY)rrzrrrrVr/r/r0r@s zCustomReSTDispatcher.roleNr'r;)rrrrrr r'r;rr3rrrrr'r rr3rrrrrVrr'r) rJ __module__ __qualname____doc__r{r~rr}rr9r@r/r/r/r0rqs      rqc@s eZdZdS)ElementLookupErrorN)rJrrr/r/r/r0rsrcsHeZdZdZdfdd Zdd d Zd fdd Zd!fdd ZZS)"sphinx_domainszcMonkey-patch directive and role dispatch, so that domain-specific markup takes precedence. envr$r'r;cs||_tdSrY)rsuperr{)rzr __class__r/r0r{szsphinx_domains.__init__typer3r2r cCs|}d|vr6|dd\}}||jjvr,|j|}t|||}|dur+|gfSn$ttd||n|jj d}|durPt|||}|durP|gfSt|jjj ||}|durb|gfSt )ztLookup a markup element (directive or role), given its name which can be a full name (with domain). :Nz%unknown directive or role name: %s:%sdefault_domain) lowersplitrdomains get_domaingetattrloggerwarningr temp_datarkstandard_domainr)rzrr2 domain_namedomainelement def_domainr/r/r0lookup_domain_element s*   z$sphinx_domains.lookup_domain_elementrrrrrrcs2z|d|WStyt|||YSw)Nr9)rrrr9rrr/r0r9,s  zsphinx_domains.directiverrrrVrrc s4z|d|WStyt||||YSw)Nr@)rrrr@rrr/r0r@7s  zsphinx_domains.role)rr$r'r;)rr3r2r3r'r rr) rJrrrr{rr9r@ __classcell__r/r/rr0rs    rc@seZdZdddZdS) WarningStreamtextr3r'r;cCsZt|}|stj|ddddS|\}}}td|}tj|||dddS)Nz r_)r)locationr) report_researchrrrstripgroupssublog)rzrmatchedrrlevelmessager/r/r0writeEs zWarningStream.writeN)rr3r'r;)rJrrrr/r/r/r0rDsrcs:eZdZedddZejejdd fdfdd ZZ S)LoggingReporterclstype[LoggingReporter]rVrr'cCs||j|j|j|j|jS)zACreate an instance of LoggingReporter from other reporter object.)source report_level halt_level debug_flag error_handler)rrVr/r/r0 from_reporterPszLoggingReporter.from_reporterFbackslashreplacerr3rrrdebugr4rr;cs(ttt}tj||||||ddS)N)r)r rrrr{)rzrrrrrstreamrr/r0r{]s   zLoggingReporter.__init__)rrrVrr'r) rr3rrrrrr4rr3r'r;) rJrr classmethodrr WARNING_LEVEL SEVERE_LEVELr{rr/r/rr0rOs rcs"eZdZdZdfdd ZZS) NullReporterz A dummy reporter; write nothing.r'r;cstddddS)Nri)rr{ryrr/r0r{nszNullReporter.__init__r)rJrrrr{rr/r/rr0rksrstatercontentrccsLz|jjj}tgd}||_|j|jj_dVW||jj_dS||jj_w)z1Switch current source input of state temporarily.N)memorVget_source_and_liner input_lines)rrgsal state_machiner/r/r0switch_source_inputrs   rcs0eZdZdZd fdd Zd fd d ZZS)SphinxFileOutputz#Better FileOutput class for Sphinx.kwargsr r'r;c s0|dd|_|ddtjdi|dS)Noverwrite_if_changedFencodingzutf-8r/)rCr setdefaultrr{)rzrrr/r0r{s zSphinxFileOutput.__init__datar3cs|jr<|jr:rrrzrrr/r/r0 get_location   zSphinxDirective.get_locationFallow_section_headingsr4 list[Node]cCst|j|j|j|dS)aParse the directive's content into nodes. :param allow_section_headings: Are titles (sections) allowed in the directive's content? Note that this option bypasses Docutils' usual checks on doctree structure, and misuse of this option can lead to an incoherent doctree. In Docutils, section nodes should only be children of ``Structural`` nodes, which includes ``document``, ``section``, and ``sidebar`` nodes. .. versionadded:: 7.4 offsetr)rrrcontent_offset)rzrr/r/r0parse_content_to_nodess z&SphinxDirective.parse_content_to_nodesrrrrrcCs |dkr|j}t|j|||dS)aParse *text* into nodes. :param text: Text, in string form. ``StringList`` is also accepted. :param allow_section_headings: Are titles (sections) allowed in *text*? Note that this option bypasses Docutils' usual checks on doctree structure, and misuse of this option can lead to an incoherent doctree. In Docutils, section nodes should only be children of ``Structural`` nodes, which includes ``document``, ``section``, and ``sidebar`` nodes. :param offset: The offset of the content. .. versionadded:: 7.4 rr)rrr)rzrrrr/r/r0parse_text_to_nodessz#SphinxDirective.parse_text_to_nodes)rr'tuple[list[Node], list[system_message]]cCs|dkr|j}|j||S)aParse *text* as inline elements. :param text: The text to parse, which should be a single line or paragraph. This cannot contain any structural elements (headings, transitions, directives, etc). :param lineno: The line number where the interpreted text begins. :returns: A list of nodes (text and inline elements) and a list of system_messages. .. versionadded:: 7.4 r)rr inline_text)rzrrr/r/r0 parse_inline szSphinxDirective.parse_inlineNr'r$r'r#)r'rr.r r'r;r'r3)F)rr4r'r)r)rr3rrrr4r'r)rr3rrr'r) rJrrrpropertyrrrrrrrrr/r/r/r0rs$      "rc@seZdZUdZded<ded<ded<ded<ded <d ed <d ed <  d(d)ddZd*ddZed+ddZed,ddZ d-d.dd Z d-d/d$d%Z d0d&d'Z dS)1 SphinxRolezA base class for Sphinx roles. This class provides helper methods for Sphinx roles. .. versionadded:: 2.0 .. note:: The subclasses of this class might not work with docutils. This class is strongly coupled with Sphinx. r3r2rawtextrrrrinlinerzdict[str, Any]options Sequence[str]rNr/ dict | Noner'rc Cs||_t||_||_||_|dur|ni|_||_|r%||_|S|j j dd|_|js7|j j j |_|js@d}t||S)N default_rolerzcannot determine default role!)r rrrr r rrr2rrrkrrrrun) rzr2r rrr r rmsgr/r/r0__call__8s     zSphinxRole.__call__cCstrY)NotImplementedErrorryr/r/r0rVszSphinxRole.runr$cCr)z[Reference to the :class:`.BuildEnvironment` object. .. versionadded:: 2.0 )r rrrryr/r/r0rYrzSphinxRole.envr#cCr)zQReference to the :class:`.Config` object. .. versionadded:: 2.0 rryr/r/r0rarzSphinxRole.config int | NonercCs|dur|j}|jj|SrY)rr rVr)rzrr/r/r0riszSphinxRole.get_source_infor.r r;cCs||\|_|_dSrYr)rzr.rr/r/r0roszSphinxRole.set_source_infocCrrrrr/r/r0rsrzSphinxRole.get_locationNr/r2r3r r3rr3rrr rr rrrr'r)r'rrrrY)rrr'r)r.r rrr'r;r) rJrrr__annotations__rrr rrrrrr/r/r/r0r s(        r csXeZdZUdZded<ded<ded<ded<edejZ ddfdd Z Z S) ReferenceRoleaA base class for reference roles. The reference roles can accept ``link title `` style as a text for the role. The parsed result; link title and target will be stored to ``self.title`` and ``self.target``. .. versionadded:: 2.0 r4has_explicit_titledisabledr3titletargetz^(.+?)\s*(?$Nr/r2r rrrr rr rrrr'rc s|duri}|d|_|j|}|r(d|_t|d|_t|d|_n d|_t||_t||_t |||||||S)N!TrF) startswithrexplicit_title_rematchrrgrouprrrr) rzr2r rrr r rrrr/r0rs     zReferenceRole.__call__rr) rJrrrrrecompileDOTALLr!rrr/r/rr0rs   rcsHeZdZdZdfdd Zdfd d Zdfdd ZdddZZS)SphinxTranslatoraA base class for Sphinx translators. This class adds a support for visitor/departure method for super node class if visitor/departure method for node class is not found. It also provides helper methods for Sphinx translators. .. versionadded:: 2.0 .. note:: The subclasses of this class might not work with docutils. This class is strongly coupled with Sphinx. rrbuilderr"r'r;cs&t|||_|j|_|j|_dSrY)rr{r(rr)rzrr(rr/r0r{s  zSphinxTranslator.__init__r.r cB|jjD]}t|d|jd}|r||dSqt|dS)z Dispatch node to appropriate visitor method. The priority of visitor method is: 1. ``self.visit_{node_class}()`` 2. ``self.visit_{super_node_class}()`` 3. ``self.unknown_visit()`` zvisit_%sN)r__mro__rrJrdispatch_visitrzr. node_classmethodrr/r0r+ zSphinxTranslator.dispatch_visitcr))z Dispatch node to appropriate departure method. The priority of departure method is: 1. ``self.depart_{node_class}()`` 2. ``self.depart_{super_node_class}()`` 3. ``self.unknown_departure()`` z depart_%sN)rr*rrJrdispatch_departurer,rr/r0r0r/z#SphinxTranslator.dispatch_departurecCstjtd||ddS)Nzunknown node type: %r)r)rrrrr/r/r0 unknown_visitszSphinxTranslator.unknown_visit)rrr(r"r'r;r) rJrrrr{r+r0r1rr/r/rr0r's  r'ztuple[Values, Reporter]__document_cache__ source_pathrr rcCs|zt\}}Wntytj|}|j|jfa\}}Ynw|dur(t|}ddlm }|j |||d}| |d|S)a&Return a new empty document object. This is an alternative of docutils'. This is a simple wrapper for ``docutils.utils.new_document()``. It caches the result of docutils' and use it on second call for instantiation. This makes an instantiation of document nodes much faster. Nr)addnodes)rr) r2 NameErrorr_utils new_documentrrVrsphinxr4r note_source)r3rcached_settingsrVdocr4rr/r/r0r7s     r7)r'r()r2r3r'r4)r2r3r9r:r'r;)r2r3r@r%r'r;)r2r3r'r;)r.rFr'r4)r.rFr'r;)rfrgr'r(rY)rrrrr'r()r3r3rr r'r)`r __future__rrir$collections.abcr contextlibrrrtypingrrr r r_r docutils.ior docutils.parsers.rstr rrdocutils.parsers.rst.statesrdocutils.statemachinerrrdocutils.utilsrr sphinx.errorsr sphinx.localerr sphinx.utilrsphinx.util.parsingr getLoggerrJrr%rrrtypesrdocutils.frontendrdocutils.nodesrr r!sphinx.buildersr" sphinx.configr#sphinx.environmentr$sphinx.util.typingr%setr&rr1r7r=r?rBrDrLrOr,r[rerorprqrrrrrrrrrr r NodeVisitorr'r7r/r/r/r0s                             5A  c1<