KcB`dZddlmZddlmZddlmZddlmZdZ dZ dZ d Z d Z d d Zd S)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`. ) defaultdict)dedent) Undefined)indentc@|dddddd}|S)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)appmetadatas :lib/python3.11/site-packages/traitlets/config/sphinxdoc.pysetupr*s1  }oNNN&*4HHH Oc| |turdSt|tttt t frt|SdS)NFT)r isinstancestrlisttupledictsetbool)dvs rinteresting_default_valuer5sG iu"sD%s344Bxx 4rcg}|D]4}t|dkrdnd}|d||d5d|S)N-z--z``, )lenappendjoin)aliasesfmtedadashess rformat_aliasesr'=sf E ))A! - '&'!'''(((( 99U  rc Zg}|j}t|dD]\}}|jj}|dz|jz}|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: rc3 K|] }d|zV dS)z``%r``N).0xs r z'class_config_rst_doc..Xs&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!rrr"valuesr default_valuedefault_value_repr Exceptionr replacer') cls trait_aliaseslines classname_traitttypefullnamer;dvr fmt_aliasess rclass_config_rst_docrLEs; E I3++4+88>>@@AA$$5(s?UZ/ %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 EEctt}|jD] \}}|||!|jD]\}\}}t |dkrpt|d}||}t |dkr@t|d} || dur!||dz| z||S)zBProduce a mapping of trait names to lists of command line aliases.rrTr*)rrr#r8r!flagsr ) r resaliasrGflagcfgrFrEcls_cfg traitnames rreverse_aliasesrUus d  C ))++!! u E %    )//++BBhsA s88q= BS ! I)nG7||q  B MM!, 9%-B C)34;;DAAA JrNct|}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) wr,=Nz )rUopenwriter _classes_inc_parentsrL)pathtitler preamblerCfcs r write_docras4$C((M dC A   s5zz!T)***   ' GGHv% & & &))++  A GG(M:: ; ; ; GGDMMMM                   sB?C--C14C1)N)__doc__ collectionsrtextwrapr traitletsrtraitlets.utils.textrrrr'rLrUrar/rrrgs!!D$#####''''''---`(r