XBFjdZddlmZddlZddlmZddlmZddl m Z m Z ddl m Z ddlmZd"d Zd#dZd$dZd%dZd&dZd'd(d!ZdS))aMachinery for documenting traitlets config options with Sphinx. This includes: - A Sphinx extension defining directives and roles for config options. - A function to generate an rst file given an Application instance. To make this documentation, first set this module as an extension in Sphinx's conf.py:: extensions = [ # ... 'traitlets.config.sphinxdoc', ] Autogenerate the config documentation by running code like this before Sphinx builds:: from traitlets.config.sphinxdoc import write_doc from myapp import MyApplication writedoc('config/options.rst', # File to write 'MyApp config options', # Title MyApplication() ) The generated rST syntax looks like this:: .. configtrait:: Application.log_datefmt Description goes here. Cross reference like this: :configtrait:`Application.log_datefmt`. ) annotationsN) defaultdict)dedent) HasTraits Undefined) Application)indentappt.Anyreturndict[str, t.Any]c<|ddddddS)zRegisters the Sphinx extension. You shouldn't need to call this directly; configure Sphinx to use this module instead. configtraitz Config option)objnameT)parallel_read_safeparallel_write_safe)add_object_type)r s HC:\PYTHON\_runtimes\venv\Lib\site-packages\traitlets/config/sphinxdoc.pysetupr.s-  }oNNN"&t D DDdvboolc| |turdSt|tttt t frt|SdS)NFT)r isinstancestrlisttupledictsetr)rs rinteresting_default_valuer 8sA iu"sD%s344Bxx 4raliases list[str]rcg}|D]4}t|dkrdnd}|d||d5d|S)N-z--z``, )lenappendjoin)r!fmtedadashess rformat_aliasesr-@se E ))A!  '&'!'''(((( 99U  rclstype[HasTraits] trait_aliasesc ^g}|j}t|dD]\}}|jj}|dz|jpdz}|d|zdgz }|jpd}|tt|dzd|vrH|td d d |j Dzn%|td |zt|jr |} n#t $rd } YnwxYw| [t#| dkr | d ddz} | dd} |td| z||r:t'||} |td| z|dd |S)zoGenerate rST documentation for this class' config options. Excludes traits defined on parent classes. T)config.z.. configtrait:: zNo description Enumz :options: r&c3 K|] }d|zV dS)z``%r``N).0xs r z'class_config_rst_doc..[s&8\8\!A8\8\8\8\8\8\rz :trait type: N@=z...z\nz\\nz:default: ``%s``z :CLI option: )__name__sorted class_traitsitems __class__namehelprstripr(r rr)valuesr default_valuedefault_value_repr Exceptionr'replacer-) r.r0lines classname_traitttypefullnamerDdvr fmt_aliasess rclass_config_rst_docrSHs7 E I3++4+88>>@@AA$$5(s?ej&6B7 %0"55z  ""6&6 VF4LL))D0111 U?? LL tyy8\8\u|8\8\8\/\/\ \]] ^ ^ ^ ^ LL% 788 9 9 9 %U%8 9 9 ? ..00    s88b==crc(U*Ckk%11 V$6$<==>>>  " @(x)@AAK LL+ =>> ? ? ?  R 99U  s=E E! E!rdict[str, list[str]]ctt}|jD] \}}|||!|jD]\}\}}t |dkr~tt|}||}t |dkrGtt|} || dur!||dz| z||S)zBProduce a mapping of trait names to lists of command line aliases.r$Tr3) rrr!rAr(flagsr'nextiter) r resaliasrNflagcfgrMrLcls_cfg traitnames rreverse_aliasesr_xs d  C ))++!! u E %    )//++BBhsA s88q==T#YYI)nG7||q   g// 9%-- C)34;;DAAA Jrpathtitlepreamble str | NoneNonect|}t|d5}||dz|dt|zdz|d|||dz|D]:}|t |||d; ddddS#1swxYwYdS)aWrite a rst file documenting config options for a traitlets application. Parameters ---------- path : str The file to be written title : str The human-readable title of the document app : traitlets.config.Application An instance of the application class to be documented preamble : str Extra text to add just after the title (optional) wr5=Nz )r_openwriter'_classes_inc_parentsrS)r`rar rbr0fcs r write_docrms2$C((M dC A   s5zz!T)***    GGHv% & & &))++  A GG(M:: ; ; ; GGDMMMM                   sB?C--C14C1)r r r r )rr r r)r!r"r r)r.r/r0r r r)r rr rT)N) r`rrarr rrbrcr rd)__doc__ __future__rtypingt collectionsrtextwrapr traitletsrrtraitlets.config.applicationrtraitlets.utils.textr rr r-rSr_rmr8rrrws!!D#"""""######********444444''''''EEEE----`(r