a ·7Ža™ã@sndZddlmZddlmZddlmZddlmZm Z dd„Z dd „Z d d „Z d d „Z dd„Zddd„ZdS)a‡Machinery 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`. é)Ú Undefined)Úindent)Ú defaultdict)rÚdedentcCs|jdddddddœ}|S)z„Registers the Sphinx extension. You shouldn't need to call this directly; configure Sphinx to use this module instead. Z configtraitz Config option)ZobjnameT)Zparallel_read_safeZparallel_write_safe)Zadd_object_type)ÚappÚmetadata©rú9lib/python3.9/site-packages/traitlets/config/sphinxdoc.pyÚsetup*s r cCs4|dus|turdSt|tttttfƒr0t|ƒSdS)NFT)rÚ isinstanceÚstrÚlistÚtupleÚdictÚsetÚbool)Zdvrrr Úinteresting_default_value4s rcCs>g}|D]*}t|ƒdkrdnd}| d||f¡qd |¡S)Néú-z--z``%s%s``ú, )ÚlenÚappendÚjoin)ÚaliasesZfmtedÚaZdashesrrr Úformat_aliases;s rc Csfg}|j}t|jdd ¡ƒD]:\}}|jj}|d|j}|d|dg7}|j ¡pZd}| t t |ƒƒd¡d|vr | t d d   d d „|j Dƒ¡ƒ¡n| t d |ƒ¡t |jƒr(z | ¡} Wntyàd} Yn0| dur(t| ƒdkr | dd…d} |  dd¡} | t d| ƒ¡||rPt||ƒ} | t d| ƒ¡| d¡qd  |¡S)zoGenerate rST documentation for this class' config options. Excludes traits defined on parent classes. T)ZconfigÚ.z.. configtrait:: ÚzNo descriptionÚ ÚEnumz :options: rcss|]}d|VqdS)z``%r``Nr)Ú.0Úxrrr Ú Xóz'class_config_rst_doc..z :trait type: Né@é=z...z\nz\\nz:default: ``%s``z :CLI option: )Ú__name__ÚsortedZ class_traitsÚitemsÚ __class__ÚnameÚhelpÚrstriprrrrÚvaluesrZ default_valueZdefault_value_reprÚ ExceptionrÚreplacer) ÚclsÚ trait_aliasesÚlinesÚ classnameÚkÚtraitZttypeÚfullnamer+ZdvrZ fmt_aliasesrrr Úclass_config_rst_docBs<ÿÿ         r7c Cs ttƒ}|j ¡D]\}}|| |¡q|j ¡D]f\}\}}t|ƒdkr4t|ƒd}||}t|ƒdkr4t|ƒd} || dur4||d|  |¡q4|S)zGProduce a mapping of trait names to lists of command line aliases. rrTr)rr rr(rÚflagsr) rÚresÚaliasr5ÚflagZcfgÚ_r3Zcls_cfgZ traitnamerrr Úreverse_aliasesus     r=NcCs¢t|ƒ}t|dƒ|}| |d¡| dt|ƒd¡| d¡|durX| |d¡| ¡D]}| t||ƒ¡| d¡q`Wdƒn1s”0YdS)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 )r=ÚopenÚwriterZ_classes_inc_parentsr7)ÚpathÚtitlerZpreambler1ÚfÚcrrr Ú write_doc‰s   rF)N)Ú__doc__Z traitletsrZtraitlets.utils.textrÚ collectionsrÚtextwrapÚ_indentrr rrr7r=rFrrrr Ús"    3