a
    õ£Beœ  ã                   @  sÆ   d Z ddlmZ ddlZddlmZ ddlmZ ddl	m
Z
mZ ddlmZ ddlmZ d	d
dœdd„Zd	ddœdd„Zdddœdd„Zdd
ddœdd„Zdddœdd„Zd$ddddd d!œd"d#„ZdS )%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`.
é    )ÚannotationsN)Údefaultdict)Údedent)Ú	HasTraitsÚ	Undefined)ÚApplication)Úindentzt.Anyzdict[str, t.Any])ÚappÚreturnc                 C  s   | j dddd� dddœ}|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)ZobjnameT)Zparallel_read_safeZparallel_write_safe)Zadd_object_type)r	   Úmetadata© r   ú]/home/yuhw/wc/wire-cell-python/wcpy/lib/python3.9/site-packages/traitlets/config/sphinxdoc.pyÚsetup.   s    
r   Úbool)Údvr
   c                 C  s4   | d u s| t u rdS t| tttttfƒr0t| ƒS dS )NFT)r   Ú
isinstanceÚstrÚlistÚtupleÚdictÚsetr   )r   r   r   r   Úinteresting_default_value9   s
    r   z	list[str]r   )Úaliasesr
   c                 C  sB   g }| D ].}t |ƒdkrdnd}| d|› |› d�¡ qd |¡S )Né   ú-z--z``ú, )ÚlenÚappendÚjoin)r   ZfmtedÚaÚdashesr   r   r   Úformat_aliasesA   s
    r!   ztype[HasTraits])ÚclsÚtrait_aliasesr
   c              	   C  sj  g }| j }t| jdd� ¡ ƒD �]>\}}|jj }|d |jp>d }|d| dg7 }|j ¡ p^d}| t	t
|ƒƒd ¡ d|v r¤| t	d	d
 dd„ |jD ƒ¡ ƒ¡ n| t	d| ƒ¡ t|jƒ�r,z| ¡ }	W n tyä   d}	Y n0 |	du�r,t|	ƒdk�r|	dd… d }	|	 dd¡}	| t	d|	 ƒ¡ || �rTt|| ƒ}
| t	d|
 ƒ¡ | d¡ qd |¡S )zoGenerate rST documentation for this class' config options.

    Excludes traits defined on parent classes.
    T)ÚconfigÚ.Ú z.. configtrait:: zNo descriptionÚ
ÚEnumz
:options: r   c                 s  s   | ]}d | V  qdS )z``%r``Nr   )Ú.0Úxr   r   r   Ú	<genexpr>\   ó    z'class_config_rst_doc.<locals>.<genexpr>z:trait type: Né@   é=   z...z\nz\\nz:default: ``%s``z:CLI option: )Ú__name__ÚsortedZclass_traitsÚitemsÚ	__class__ÚnameÚhelpÚrstripr   r   r   r   Úvaluesr   Údefault_valueZdefault_value_reprÚ	Exceptionr   Úreplacer!   )r"   r#   ÚlinesÚ	classnameÚ_ÚtraitÚttypeÚfullnamer4   ZdvrZfmt_aliasesr   r   r   Úclass_config_rst_docI   s4    &


r@   r   zdict[str, list[str]]c           
      C  s    t tƒ}| j ¡ D ]\}}||  |¡ q| j ¡ D ]f\}\}}t|ƒdkr4tt|ƒƒ}|| }t|ƒdkr4tt|ƒƒ}	||	 du r4||d |	   |¡ q4|S )zBProduce a mapping of trait names to lists of command line aliases.r   Tr%   )	r   r   r   r1   r   Úflagsr   ÚnextÚiter)
r	   ÚresÚaliasr=   ÚflagÚcfgr<   r;   Zcls_cfgZ	traitnamer   r   r   Úreverse_aliasesy   s    rH   z
str | NoneÚNone)ÚpathÚtitler	   Úpreambler
   c                 C  s¢   t |ƒ}t| dƒ�|}| |d ¡ | dt|ƒ d ¡ | d¡ |durX| |d ¡ | ¡ D ]}| t||ƒ¡ | d¡ q`W d  ƒ n1 s”0    Y  dS )a�  Write 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

)rH   ÚopenÚwriter   Z_classes_inc_parentsr@   )rJ   rK   r	   rL   r#   ÚfÚcr   r   r   Ú	write_doc�   s    
rS   )N)Ú__doc__Ú
__future__r   ÚtypingÚtÚcollectionsr   Útextwrapr   Z	traitletsr   r   Ztraitlets.config.applicationr   Ztraitlets.utils.textr   r   r   r!   r@   rH   rS   r   r   r   r   Ú<module>   s   "0