o HTh@sdZddlmZddlZddlmZddlmZddl m Z m Z ddl m Z ddlmZd(d dZd)ddZd*ddZd+ddZd,dd Zd-d.d&d'ZdS)/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)indentappt.Anyreturndict[str, t.Any]cCs|jdddddddS)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)r r]/home/air/segue/gemini/backup/venv/lib/python3.10/site-packages/traitlets/config/sphinxdoc.pysetup.s rdvboolcCs4|dus|tur dSt|tttttfrt|SdS)NFT)r isinstancestrlisttupledictsetr)rrrrinteresting_default_value8s raliases list[str]rcCsBg}|D]}t|dkrdnd}|d||dqd|S)N-z--z``, )lenappendjoin)rfmtedadashesrrrformat_aliases@s  r)clstype[HasTraits] trait_aliasesc Cs`g}|j}t|jddD]\}}|jj}|d|jpd}|d|dg7}|jp.d}|t t |dd|vrQ|t d d d d |j Dn |t d |t |jrz|} Wn typd} Ynw| durt| dkr| ddd} | dd} |t d| ||rt||} |t d| |dqd |S)zoGenerate rST documentation for this class' config options. Excludes traits defined on parent classes. T)config.z.. configtrait:: zNo description Enumz :options: r"css|]}d|VqdS)z``%r``Nr).0xrrr [sz'class_config_rst_doc..z :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)) r*r,lines classname_traitttypefullnamer=dvr fmt_aliasesrrrclass_config_rst_docHs6&        rLrdict[str, list[str]]c Cstt}|jD] \}}|||q |jD]3\}\}}t|dkrMtt|}||}t|dkrMtt|} || durM||d| |q|S)zBProduce a mapping of trait names to lists of command line aliases.r Tr.) rrrr:r$flagsr#nextiter) r resaliasrGflagcfgrFrEcls_cfg traitnamerrrreverse_aliasesxs     rWpathtitlepreamble str | NoneNonecCst|}t|d?}||d|dt|d|d|dur,||d|D]}|t|||dq0WddS1sKwYdS)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) wr0=Nz )rWopenwriter#_classes_inc_parentsrL)rXrYr rZr,fcrrr write_docs    "rd)r r r r )rr r r)rrr r)r*r+r,r r r)r rr rM)N) rXrrYrr rrZr[r r\)__doc__ __future__rtypingt collectionsrtextwrapr traitletsrrtraitlets.config.applicationrtraitlets.utils.textrrrr)rLrWrdrrrrs "        0