_dB^dZddlmZddlmZddlmZddlmZdZ dZ dZ d Z d Z d d Zy )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)indentc8|jdddddd}|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 |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: rc3&K|] }d|z yw)z``%r``N).0xs r z'class_config_rst_doc..Xs8\!A8\sz :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+8>>@A$5((s?UZZ/ %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]i\}\}}t |dk(st|d}||}t |dk(s:t|d} || dusP||dz| zj |k|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 % ! ))//+BhsA s8q=S ! I)nG7|q  M!, 9%- C)34;;DAB JrNct|}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 )rUopenwriter _classes_inc_parentsrL)pathtitler preamblerCfcs r write_docras$C(M dC A   s5z!T)*    GGHv% &))+ A GG(M: ; GGDM    s BB??C)N)__doc__ collectionsrtextwrapr traitletsrtraitlets.utils.textrrrr'rLrUrar/rrrgs8!D$'-`(r