~fdZddlmZddlZddlmZddlmZddl m Z m Z ddl m Z ddlmZdd Zdd Zdd Zdd Zdd ZdddZy)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)indentc4|jddddddS)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)apps U/var/www/cvtools/html/venv/lib/python3.12/site-packages/traitlets/config/sphinxdoc.pysetupr.s$  }oN"&t DDcz||turyt|tttt t fr t|Sy)NFT)r isinstancestrlisttupledictsetbool)dvs rinteresting_default_valuer8s1 i"sD%s34Bx rcg}|D]+}t|dk(rdnd}|jd||d-dj|S)N-z--z``, )lenappendjoin)aliasesfmtedadashess rformat_aliasesr)@sQ E )A!  r&!B'() 99U rc g}|j}t|jdjD]\}}|jj}|dz|j xsdz}|d|zdgz }|j jxsd}|jtt|dzd|vr>|jtd d jd |jDzn|jtd |zt|jrX |j} | Et#| dkDr| d ddz} | j%dd} |jtd| z||r+t'||} |jtd| z|jddj|S#t $rd } YwxYw)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|z yw)z``%r``N).0xs r z'class_config_rst_doc..[s8\!A8\sz :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)) cls trait_aliaseslines classname_traitttypefullnamer=dvr fmt_aliasess rclass_config_rst_docrNHs E I3++4+8>>@A$5((s?ejj&6B7 %0"55zz  "6&6 VF4L)D01 U? LL tyy8\u||8\/\ \] ^ LL% 78 9 %U%8%8 9 ..0s8b=cr(U*Ckk%1 V$6$<=>  "(x)@AK LL+ => ?  RI$L 99U #  s.G G('G(ctt}|jjD]\}}||j ||j jD]u\}\}}t |dk(stt|}||}t |dk(s@tt|} || dus\||dz| zj |w|S)zBProduce a mapping of trait names to lists of command line aliases.rTr,) rrr%r:r#flagsr"nextiter) rresaliasrIflagcfgrHrGcls_cfg traitnames rreverse_aliasesrYxs d C ))+! u E % ! ))//+BhsA s8q=T#YI)nG7|q  g/ 9%- C)34;;DAB Jrct|}t|d5}|j|dz|jdt|zdz|jd||j|dz|j D].}|jt |||jd0 dddy#1swYyxYw)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 )rYopenwriter"_classes_inc_parentsrN)pathtitlerpreamblerEfcs r write_docres$C(M dC A   s5z!T)*    GGHv% &))+ A GG(M: ; GGDM    s BB??C)rt.Anyreturndict[str, t.Any])rrfrgr)r%z list[str]rgr)rDztype[HasTraits]rErhrgr)rrrgzdict[str, list[str]])N) r`rrarrrrbz str | NonergNone)__doc__ __future__rtypingt collectionsrtextwrapr traitletsrrtraitlets.config.applicationrtraitlets.utils.textr rrr)rNrYrer1rrrssB!D##*4'E-`(r