3
T'ícéQ ã @ s¸ U d Z ddlZddlZddlmZ ddlmZ ddlmZ ddlmZ ddl m
Z
m Z m Z m
Z
mZmZmZmZmZmZmZmZ ddlZddlmZ dd lmZ dd
lmZm Z m Z dd l m Z m Z m!Z! dd l"m#Z# dd
l$m%Z%m&Z&m'Z' ddl(m)Z)m*Z* ddl+m,Z, ddl-m.Z. ddl/m0Z0m1Z1 ddl2m3Z3 ddl4m5Z5 e3j6e7Z8ej9dZ:e rtddl;m<Z< ddl=m>Z> ddl?m@Z@ e,jAejBjCZDeE ZFeee FeedY dddZGeHeIdd d ZJeHee dd d d ZKeHeIdd!d"ZLeHe5dd#d$d%ZMeHddd&d'ZNee eId(d)d*ZOee dd(d+d,ZPee dd(d-d.ZQeedZ dd/d0ZReed[ dd1d2ZSeeeH ed\ d3d4d5ZTed]eeH ed^ d3d6d7ZUG d8d9 d9ZVG d:d; d;eWZXG d<d= d=eVZYG d>d? d?ZZG d@dA dAe)Z[G dBdC dCe)Z\eIddDdEZ]ee%e'ed_ dFdGdHZ^G dIdJ dJeZ_G dKdL dLe Z`G dMdN dNZaG dOdP dPeaZbG dQdR dRejcZdeDd`k rdTdU Zeeee _edafeejg fdaeHe ejgdVdWdXZhdS )bz Utility functions for docutils.é N)Úcontextmanager)Úcopy)Úpath)Ú
ModuleType) ÚIOÚ
TYPE_CHECKINGÚAnyÚCallableÚDictÚ GeneratorÚListÚOptionalÚSetÚTupleÚTypeÚcast)Únodes)Ú
FileOutput)ÚElementÚNodeÚsystem_message)Ú DirectiveÚ
directivesÚroles)ÚInliner)ÚStateÚ StateMachineÚ
StringList)ÚReporterÚunescape)Úversion)Ú SphinxError)Ú_Ú__)Úlogging)Ú RoleFunctionz>^(.+?:(?:\d+)?): \((DEBUG|INFO|WARNING|ERROR|SEVERE)/(\d+)?\) )ÚBuilder)ÚConfig)ÚBuildEnvironment)Úreturnc c sV z t tj} t tj}dV W d| t_|t_x"ttD ]}t| tj| q6W X dS )z"Create namespace for reST parsers.N) r r Ú _directivesr Ú_rolesÚlistÚadditional_nodesÚunregister_nodeÚdiscard)r* r+ Únode© r1 ú6/tmp/pip-build-gk9425m9/sphinx/sphinx/util/docutils.pyÚdocutils_namespace( s
r3 )Únamer) c C s
| t jkS )z1Check the *name* directive is already registered.)r r* )r4 r1 r1 r2 Úis_directive_registered9 s r5 )r4 Ú directiver) c C s t j| | 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)r Úregister_directive)r4 r6 r1 r1 r2 r7 > s r7 c C s
| t jkS )z,Check the *name* role is already registered.)r r+ )r4 r1 r1 r2 Úis_role_registeredG s r8 )r4 Úroler) c C s t j| | dS )z¨Register 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)r Zregister_local_role)r4 r9 r1 r1 r2 Ú
register_roleL s r: c C s t jj| d dS )z Unregister a role from docutils.N)r r+ Úpop)r4 r1 r1 r2 Úunregister_roleU s r< )r0 r) c C s t tjd| j S )z'Check the *node* is already registered.Úvisit_)Úhasattrr ÚGenericNodeVisitorÚ__name__)r0 r1 r1 r2 Úis_node_registeredZ s rA c C s. t tjd| j s*tj| jg tj| dS )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.
r= N)r> r r? r@ Z_add_node_class_namesr- Úadd)r0 r1 r1 r2 Ú
register_node_ s rC c C s^ t tjd| j rZttjd| j ttjd| j ttjd| j ttjd| j dS )zaUnregister a node from docutils.
This is inverse of ``nodes._add_nodes_class_names()``.
r= Zdepart_N)r> r r? r@ ÚdelattrZSparseNodeVisitor)r0 r1 r1 r2 r. j s
r. c # sF ddl m dtttd fdd
} z| tj_dV W d tj_X dS )z½Patch 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_codeÚreporterr) c s | S )Nr1 )rF rG )rE r1 r2 Úpatched_get_language s z2patched_get_language.<locals>.patched_get_language)N)Zdocutils.languagesrE Ústrr r ÚdocutilsÚ languages)rH r1 )rE r2 rH v s
rH c # sN ddl m dtttd fdd
} z| tjjj_dV W d tjjj_X dS )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
r )rE N)rF rG r) c s | S )Nr1 )rF rG )rE r1 r2 rH s z6patched_rst_get_language.<locals>.patched_get_language)N) Z docutils.parsers.rst.languagesrE rI r r rJ ÚparsersZrstrK )rH r1 )rE r2 Úpatched_rst_get_language s
rM )Úconfdirr) c c s^ z4t jjdd}| r,tjtj| dt jd< dV W d|dkrNt jjdd n
|t jd< X dS )z?Let docutils know the location of ``docutils.conf`` for Sphinx.ZDOCUTILSCONFIGNz
docutils.conf)ÚosÚenvironÚgetr ÚjoinÚabspathr; )rN Zdocutilsconfigr1 r1 r2 Úusing_user_docutils_conf¢ s
rT c c sB t 2 t t| dV W dQ R X W dQ R X W dQ R X dS )z Patch to docutils temporarily.N)rH rM rT )rN r1 r1 r2 Úpatch_docutils² s rU c @ s¬ e Zd ZdZddddZddddZee eeddd d
Z ddd d Z
ddd
dZ e e
ejeeee ee f dddZe e
eeeeee f dddZdS )ÚCustomReSTDispatcherzCustom reST's mark-up dispatcher.
This replaces docutils's directives and roles dispatch mechanism for reST parser
by original one temporarily.
N)r) c C s dd | _ dd | _d S )Nc W s d g fS )Nr1 )Úargsr1 r1 r2 Ú<lambda>Á s z/CustomReSTDispatcher.__init__.<locals>.<lambda>c W s d g fS )Nr1 )rW r1 r1 r2 rX Â s )Údirective_funcZ
roles_func)Úselfr1 r1 r2 Ú__init__À s
z CustomReSTDispatcher.__init__c C s | j d S )N)Úenable)rZ r1 r1 r2 Ú __enter__Ä s z CustomReSTDispatcher.__enter__)Úexc_typeÚ exc_valueÚ tracebackr) c C s | j d S )N)Údisable)rZ r^ r_ r` r1 r1 r2 Ú__exit__Ç s z CustomReSTDispatcher.__exit__c C s$ t j| _tj| _| jt _| jt_d S )N)r r6 rY r r9 Ú role_func)rZ r1 r1 r2 r\ Ê s zCustomReSTDispatcher.enablec C s | j t_| jt_d S )N)rY r r6 rc r r9 )rZ r1 r1 r2 ra Ñ s z CustomReSTDispatcher.disable)Údirective_nameÚlanguage_moduleÚdocumentr) c C s | j |||S )N)rY )rZ rd re rf r1 r1 r2 r6 Õ s z CustomReSTDispatcher.directive)Ú role_namere ÚlinenorG r) c C s | j ||||S )N)rc )rZ rg re rh rG r1 r1 r2 r9 Ú s zCustomReSTDispatcher.role)r@ Ú
__module__Ú __qualname__Ú__doc__r[ r] r Ú Exceptionr rb r\ ra rI r r rf r r
r r r r6 Úintr r% r9 r1 r1 r1 r2 rV ¹ s "rV c @ s e Zd ZdS )ÚElementLookupErrorN)r@ ri rj r1 r1 r1 r2 rn ß s rn c s e Zd ZdZddd fdd Zeeeddd Zeee j
e e e
e ee f d
fd d Zeeeee eee f d
fdd Z ZS )Úsphinx_domainszcMonkey-patch directive and role dispatch, so that domain-specific
markup takes precedence.
r( N)Úenvr) c s || _ t j d S )N)rp Úsuperr[ )rZ rp )Ú __class__r1 r2 r[ ç s zsphinx_domains.__init__)Útyper4 r) c C sÎ |j }d|krl|jdd\}}|| jjkrX| jj|}t|||}|dk rj|g fS q tjtd|| n4| jj j
d}|dk r t|||}|dk r |g fS t| jjd||}|dk rÆ|g fS t dS )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:%sZdefault_domainZstd) ÚlowerÚsplitrp ÚdomainsZ
get_domainÚgetattrÚloggerÚwarningr" Ú temp_datarQ rn )rZ rs r4 Z domain_nameÚdomainÚelementZ
def_domainr1 r1 r2 Úlookup_domain_elementë s$
z$sphinx_domains.lookup_domain_element)rd re rf r) c s2 y | j d|S tk
r, t j|||S X d S )Nr6 )r rn rq r6 )rZ rd re rf )rr r1 r2 r6 s zsphinx_domains.directive)rg re rh rG r) c s4 y | j d|S tk
r. t j||||S X d S )Nr9 )r rn rq r9 )rZ rg re rh rG )rr r1 r2 r9 s zsphinx_domains.role)r@ ri rj rk r[ rI r r r r rf r r
r r r r r6 rm r r% r9 Ú
__classcell__r1 r1 )rr r2 ro ã s &ro c @ s e Zd ZeddddZdS )Ú
WarningStreamN)Útextr) c C sR t j|}|s tj|jd n.|j \}}}t jd|j }tj|||d d S )Nz
Ú )Úlocation)Ú report_reÚsearchrz r{ ÚrstripÚgroupsÚsubÚlog)rZ r Úmatchedr rs ÚlevelÚmessager1 r1 r2 Úwrite s
zWarningStream.write)r@ ri rj rI r r1 r1 r1 r2 r s r c sN e Zd Zeed dddZejejddfee e e
edd fdd
Z Z S )
ÚLoggingReporter)rG r) c C s | |j |j|j|j|jS )zACreate an instance of LoggingReporter from other reporter object.)ÚsourceÚ report_levelÚ
halt_levelZ
debug_flagÚ
error_handler)ÚclsrG r1 r1 r2 Ú
from_reporter% s z LoggingReporter.from_reporterFÚbackslashreplaceN)r r r Údebugr r) c s( t tt }t j||||||d d S )N)r )r r r rq r[ )rZ r r r r r Ústream)rr r1 r2 r[ + s zLoggingReporter.__init__)
r@ ri rj Ú classmethodr r Z
WARNING_LEVELZ SEVERE_LEVELrI rm Úboolr[ r r1 r1 )rr r2 r $ s
r c s& e Zd ZdZdd fdd Z ZS )Ú NullReporterz A dummy reporter; write nothing.N)r) c s t jddd d S )Nr iç é )rq r[ )rZ )rr r1 r2 r[ 6 s zNullReporter.__init__)r@ ri rj rk r[ r r1 r1 )rr r2 r 3 s r c C s t dkS )Nr é
)r r r )Ú__version_info__r1 r1 r1 r2 Úis_html5_writer_available: s r )ÚstateÚcontentr) c c sB z0| j jj}tg d}||_|j| j j_dV W d|| j j_X dS )z1Switch current source input of state temporarily.N)ÚmemorG Úget_source_and_liner Z input_lines)r r¡ r£ Ú
state_machiner1 r1 r2 Úswitch_source_input> s
r¥ c s< e Zd ZdZedd fdd Zeed fdd Z ZS ) ÚSphinxFileOutputz#Better FileOutput class for Sphinx.N)Úkwargsr) c s |j dd| _t jf | d S )NÚoverwrite_if_changedF)r; r¨ rq r[ )rZ r§ )rr r1 r2 r[ S s zSphinxFileOutput.__init__)Údatar) c sb | j rV| jrVd| jkrV| jrVtjj| j rVt| j | jd}|j |krL|S W d Q R X t
j |S )NÚb)Úencoding) Zdestination_pathZ autocloseÚmoder¨ rO r ÚexistsÚopenr« Úreadrq r )rZ r© Úf)rr r1 r2 r W s zSphinxFileOutput.write) r@ ri rj rk r r[ rI r r r1 r1 )rr r2 r¦ P s r¦ c @ sh e Zd ZdZeddddZeddddZeee f dd d
Z
e d d d
dZ edddZ
d S )ÚSphinxDirectivezëA base class for Sphinx directives.
This class provides helper methods for Sphinx directives.
.. note:: The subclasses of this class might not work with docutils.
This class is strongly coupled with Sphinx.
r( )r) c C s | j jjjS )z3Reference to the :class:`.BuildEnvironment` object.)r rf Úsettingsrp )rZ r1 r1 r2 rp k s zSphinxDirective.envr' c C s | j jS )z)Reference to the :class:`.Config` object.)rp Úconfig)rZ r1 r1 r2 r³ p s zSphinxDirective.configc C s | j j| jS )zGet source and line number.)r¤ r£ rh )rZ r1 r1 r2 Úget_source_infou s z SphinxDirective.get_source_infoN)r0 r) c C s | j \|_|_dS )z'Set source and line number to the node.N)r´ r Úline)rZ r0 r1 r1 r2 Úset_source_infoy s z SphinxDirective.set_source_infoc C s dj dd | j D S )z&Get current location info for logging.rt c s s | ]}t |V qd S )N)rI )Ú.0Úsr1 r1 r2 ú <genexpr> s z/SphinxDirective.get_location.<locals>.<genexpr>)rR r´ )rZ r1 r1 r2 Ú get_location} s z SphinxDirective.get_location)r@ ri rj rk Úpropertyrp r³ r rI rm r´ r r¶ rº r1 r1 r1 r2 r± b s r± c @ sæ e Zd ZU dZeeee e
e
ee i g feeeee
e ee eee ee f dddZeee ee f dddZeddd d
Zed dd d
Zdeeeef dddZdeeddddZedddZdS )Ú
SphinxRolezáA base class for Sphinx roles.
This class provides helper methods for Sphinx roles.
.. note:: The subclasses of this class might not work with docutils.
This class is strongly coupled with Sphinx.
)r4 Úrawtextr rh ÚinlinerÚoptionsr¡ r) c C sr || _ t|| _|| _|| _|| _|| _|r8|j | _n2| j j
j dd| _| js\| j j j
| _| jsjtd| j S )NÚ default_roler z cannot determine default role!)r½ r r rh r¾ r¿ r¡ rv r4 rp r| rQ r³ rÀ r! Úrun)rZ r4 r½ r rh r¾ r¿ r¡ r1 r1 r2 Ú__call__ s
zSphinxRole.__call__)r) c C s t d S )N)ÚNotImplementedError)rZ r1 r1 r2 rÁ ª s zSphinxRole.runr( c C s | j jjjS )z3Reference to the :class:`.BuildEnvironment` object.)r¾ rf r² rp )rZ r1 r1 r2 rp s zSphinxRole.envr' c C s | j jS )z)Reference to the :class:`.Config` object.)rp r³ )rZ r1 r1 r2 r³ ² s zSphinxRole.configN)rh r) c C s |d kr| j }| jjj|S )N)rh r¾ rG r£ )rZ rh r1 r1 r2 r´ · s zSphinxRole.get_source_info)r0 rh r) c C s | j |\|_|_d S )N)r´ r rµ )rZ r0 rh r1 r1 r2 r¶ ¼ s zSphinxRole.set_source_infoc C s dj dd | j D S )z&Get current location info for logging.rt c s s | ]}t |V qd S )N)rI )r· r¸ r1 r1 r2 r¹ Á s z*SphinxRole.get_location.<locals>.<genexpr>)rR r´ )rZ r1 r1 r2 rº ¿ s zSphinxRole.get_location)N)N)r@ ri rj rk rI r4 r½ r rm rh r r¾ r
r¿ r r¡ r r r r rÁ r» rp r³ r´ r¶ rº r1 r1 r1 r2 r¼ s$
r¼ c sn e Zd ZU dZeeee e
j de
j Z
i g feeeeeeee eee ee f d fdd
Z ZS )Ú
ReferenceRolezèA base class for reference roles.
The reference roles can accept ``link title <target>`` style as a text for
the role. The parsed result; link title and target will be stored to
``self.title`` and ``self.target``.
z^(.+?)\s*(?<!\x00)<(.*?)>$)r4 r½ r rh r¾ r¿ r¡ r) c sv |j d| _| jj|}|rDd| _t|jd| _t|jd| _nd| _t|| _t|| _t j
|||||||S )Nú!Tru é F) Ú
startswithÚdisabledÚexplicit_title_reÚmatchÚhas_explicit_titler ÚgroupÚtitleÚtargetrq r ) rZ r4 r½ r rh r¾ r¿ r¡ r )rr r1 r2 rÂ Ó s
zReferenceRole.__call__)r@ ri rj rk r rË rÈ rI rÍ rÎ ÚreÚcompileÚDOTALLrÉ rm r r
r r r r r r r1 r1 )rr r2 rÄ Ä s
rÄ c sd e Zd ZdZejddd fdd Zedd fdd Zedd fd
d Z eddd d
Z
Z S )ÚSphinxTranslatorax A 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.
.. note:: The subclasses of this class might not work with docutils.
This class is strongly coupled with Sphinx.
r& N)rf Úbuilderr) c s& t j| || _|j| _|j| _d S )N)rq r[ rÓ r³ r² )rZ rf rÓ )rr r1 r2 r[ ò s zSphinxTranslator.__init__)r0 r) c sB x<|j jD ]$}t| d|j d}|r
|| P q
W t j| 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)rr Ú__mro__ry r@ rq Údispatch_visit)rZ r0 Ú
node_classÚmethod)rr r1 r2 rÕ ø s z SphinxTranslator.dispatch_visitc sB x<|j jD ]$}t| d|j d}|r
|| P q
W t j| dS )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 rÔ ry r@ rq Údispatch_departure)rZ r0 rÖ r× )rr r1 r2 rØ s z#SphinxTranslator.dispatch_departurec C s t jtd||d d S )Nzunknown node type: %r)r )rz r{ r# )rZ r0 r1 r1 r2 Ú
unknown_visit s z SphinxTranslator.unknown_visit) r@ ri rj rk r rf r[ r rÕ rØ rÙ r r1 r1 )rr r2 rÒ æ s
rÒ é c O s t | j||S )N)ÚiterZtraverse)rZ rW r§ r1 r1 r2 Úfindall" s rÜ )Ú source_pathr² r) c C sT t dkrtjj| a |dkr&tt j}ddlm} |j|t j | d}|j
| 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)r ru éÿÿÿÿ) Ú__document_cache__rJ ÚutilsÚ new_documentr r² ZsphinxrÞ rf rG Z note_source)rÝ r² rÞ rf r1 r1 r2 râ - s
râ )NNN)NNN)NNN)NNN)N)NNN)NNN)r rÚ )N)irk rO rÏ Ú
contextlibr r r Útypesr Útypingr r r r r
r r r
r r r r rJ r Z docutils.ior Zdocutils.nodesr r r Zdocutils.parsers.rstr r r Zdocutils.parsers.rst.statesr Zdocutils.statemachiner r r Zdocutils.utilsr r Ú packagingr Z
sphinx.errorsr! Z
sphinx.localer" r# Z sphinx.utilr$ Zsphinx.util.typingr% Ú getLoggerr@ rz rÐ r
Zsphinx.buildersr& Z
sphinx.configr' Zsphinx.environmentr( ÚparseÚ __version__Úreleaser Úsetr- r3 rI r r5 r7 r8 r: r< rA rC r. rH rM rT rU rV rl rn ro r r r r r¥ r¦ r± r¼ rÄ Ú NodeVisitorrÒ rÜ rà rf râ r1 r1 r1 r2 Ú<module> s 8
&6 B";