B èéNcBã@sjdZddlmZddlmZddlmZddlmZdd„Z dd „Z d d „Z d d „Z dd„Z ddd„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`. é)Ú defaultdict)Údedent)Ú Undefined)ÚindentcCs|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)ÚappZmetadata©rú9lib/python3.7/site-packages/traitlets/config/sphinxdoc.pyÚsetup*s r cCs4|dks|tkrdSt|tttttfƒr0t|ƒSdS)NFT)rÚ isinstanceÚstrÚlistÚtupleÚdictÚsetÚbool)ZdvrrrÚinteresting_default_value5s rcCsFg}x6|D].}t|ƒdkrdnd}| d|›|›d¡q Wd |¡S)Néú-z--z``z, )ÚlenÚappendÚjoin)ÚaliasesZfmtedÚaZdashesrrrÚformat_aliases=s  rc Csng}|j}xVt|jdd ¡ƒD]<\}}|jj}|d|j}|d|dg7}|j ¡p^d}| t t |ƒƒd¡d|kr¤| t d d   d d „|j Dƒ¡ƒ¡n| t d |ƒ¡t |jƒr.y | ¡} Wntk ræd} YnX| dk r.t| ƒdkr| dd…d} |  dd¡} | t d| ƒ¡||rVt||ƒ} | t d| ƒ¡| d¡q"Wd  |¡S)zoGenerate rST documentation for this class' config options. Excludes traits defined on parent classes. T)ZconfigÚ.z.. configtrait:: ÚzNo descriptionÚ ÚEnumz :options: z, css|]}d|VqdS)z``%r``Nr)Ú.0Úxrrrú Xsz'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Ú_ÚtraitZttypeÚfullnamer(ZdvrZ fmt_aliasesrrrÚclass_config_rst_docEs4"&       r4c Cs¨ttƒ}x$|j ¡D]\}}|| |¡qWxt|j ¡D]f\}\}}t|ƒdkr:t|ƒd}||}t|ƒdkr:t|ƒd} || dkr:||d|  |¡q:W|S)zBProduce a mapping of trait names to lists of command line aliases.rrTr)rr rr%rÚflagsr) rZresÚaliasr2ÚflagZcfgr1r0Zcls_cfgZ traitnamerrrÚreverse_aliasesus     r8Nc Cs’t|ƒ}t|dƒv}| |d¡| dt|ƒd¡| d¡|dk rX| |d¡x*| ¡D]}| t||ƒ¡| d¡qbWWdQRXdS)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 )r8ÚopenÚwriterZ_classes_inc_parentsr4)ÚpathÚtitlerZpreambler.ÚfÚcrrrÚ write_doc‰s  rA)N)Ú__doc__Ú collectionsrÚtextwraprZ traitletsrZtraitlets.utils.textrr rrr4r8rArrrrÚ"s     0