o
    BZh                     @  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Zd)ddZd*ddZd+ddZd,dd Z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)indentappt.Anyreturndict[str, t.Any]c                 C  s   | j dddd dddS )zRegisters 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	    r   Q/var/www/html/lang_env/lib/python3.10/site-packages/traitlets/config/sphinxdoc.pysetup.   s   
r   dvboolc                 C  s4   | d u s| t u r
dS t| tttttfrt| S dS )NFT)r   
isinstancestrlisttupledictsetr   )r   r   r   r   interesting_default_value8   s
   r   aliases	list[str]r   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_aliases@   s
   
r#   clstype[HasTraits]trait_aliasesc              	   C  s`  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 rQ|t	d	d
dd |jD   n	|t	d|  t|jrz| }	W n typ   d}	Y nw |	durt|	dkr|	dd d }	|	dd}	|t	d|	  || rt|| }
|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>[   s    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fullnamer6   ZdvrZfmt_aliasesr   r   r   class_config_rst_docH   s6   &

rB   r   dict[str, list[str]]c           
      C  s   t t}| j D ]\}}|| | q	| j D ]3\}\}}t|dkrMtt|}|| }t|dkrMtt|}	||	 du rM||d |	  | q|S )zBProduce a mapping of trait names to lists of command line aliases.r   Tr(   )	r   r   r   r3   r   flagsr   nextiter)
r	   resaliasr?   flagcfgr>   r=   Zcls_cfgZ	traitnamer   r   r   reverse_aliasesx   s   rK   pathtitlepreamble
str | NoneNonec                 C  s   t |}t| d?}||d  |dt| d  |d |dur,||d  | D ]}|t|| |d q0W d   dS 1 sKw   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

)rK   openwriter   Z_classes_inc_parentsrB   )rL   rM   r	   rN   r&   fcr   r   r   	write_doc   s   
"rW   )r	   r
   r   r   )r   r
   r   r   )r   r   r   r   )r$   r%   r&   r   r   r   )r	   r   r   rC   )N)
rL   r   rM   r   r	   r   rN   rO   r   rP   )__doc__
__future__r   typingtcollectionsr   textwrapr   Z	traitletsr   r   Ztraitlets.config.applicationr   Ztraitlets.utils.textr   r   r   r#   rB   rK   rW   r   r   r   r   <module>   s    "





0