lKjlCdZddlmZddlmZddlmZmZmZm Z m Z m Z m Z m Z mZmZmZerddlmZdedeefdZded edeefd Zd%d d d edeed ffdZdedeed fdeedeedzdeedzdef dZdeeddfdZ d&d d ded edededeedzdededeedzdeedzd ed!ed"ed#edzdefd$Zy)'z9RST documentation generation functions for cyclopts apps.) TYPE_CHECKING) extract_text) adjust_filters_for_subcommandapply_usage_nameextract_description extract_usagegenerate_anchor get_app_infois_all_builtin_flagsiterate_commandsnormalize_command_filtersshould_include_commandshould_show_usage)Apptitlereturncddd|gS)zCreate an RST code block containing the title. Parameters ---------- title : str Title text to display in code block. Returns ------- list[str] RST formatted code block lines. z.. code-block:: textz rs b/Users/ahmed/devFolder/Ultron/claude-voice/.venv/lib/python3.12/site-packages/cyclopts/docs/rst.pymake_rst_code_block_titlers  eW  levelctddddddd}|dkrd}n|d kDrd }||}|t|z}|dk(r|||gS||gS) zCreate an RST section header. Parameters ---------- title : str Section title. level : int Heading level (1-6). Returns ------- list[str] RST formatted section header lines. =-^"'~)r"r')len)rrmarkersmarker underlines rmake_rst_section_headerr,,sm       G qy  U^FU#I z5),,y!!rapprinclude_hiddencTi}|jrt||D] \}}|||< |S)a/Build mapping of command names to App objects. Parameters ---------- app : App The app to extract commands from. include_hidden : bool Whether to include hidden commands. Returns ------- dict[str, App] Mapping of command names to App instances. ) _commandsr )r-r. command_mapnamesubapps r_build_command_mapr4Rs6K }},S.ALD& &K B rentriesr1 parent_pathnormalized_filterNnormalized_excludecg}|D]j}|js|jd}|j|}||5|8|j|Jt|||||sZ|j|l|S)aFilter command entries based on inclusion/exclusion rules. Parameters ---------- entries : list Command entries to filter. command_map : dict[str, App] Mapping of command names to App objects. parent_path : list[str] Parent command path. normalized_filter : set[str] | None Normalized filter set. normalized_exclude : set[str] | None Normalized exclude set. Returns ------- list Filtered command entries. r)namesgetappendr) r5r1r6r7r8filtered_entriesentrycmd_namer3s r_filter_command_entriesr@hs6 ;;{{1~H __X.F~$,1C1K$++E2*(KARTfhno$++E2 rlinesc|jd|jd|jd|jdy)zGenerate table of contents using RST contents directive. The `.. contents::` directive automatically generates a TOC from section headings, which is the idiomatic approach for RST/Sphinx. z.. contents:: Table of Contentsz :local:z :depth: 6rN)r<)rAs r _generate_tocrCs5  LL23 LL LL  LLr recursive heading_levelmax_heading_level command_chain generate_tocflatten_commandscommands_filterexclude_commands no_root_titlecode_block_title skip_preamble usage_namec ddlm}g}|g}t||\}}}|r|s|d}n|r|}n|}dg}|r|j|n|j |t dj |jdd}|j d |d |j d | r|s|}n|r|r|}n|r|t|zd z n|}t||}| r|r<| r t|}n t||}|j||j d |jjd d}| st|r| r|rt|}d}|rzt!|t"r|}nt%|dd}t'|| }|rK|j)dd }t|d kDrdj |d|d }ndj |}|r]|j d|j d |j)dD]}|j d||j d | sRt+||}|rD|dv}t%|d|} | r0|j | j-|j d |r|s|j.r t1||j|g5|j3g|}!dddt5|| \}"}#g}$t7|d}%||d z|}&!D]\}'}(|s|'r |'j8s| r|s|(j:dk(r|(j<D)cgc]'})|)j>rtA||)j>r&|))}*})|*sltC|*|%|$|"|#}+|+s~|(jDr0|j d|(jDd|j d |+D]q},|,j>r|,j>dnd }-t%|,jFd}.|j d|-d|.r|j d|.|j d s2|(j:dk(sC|&jI|(jKd }/|&dd|/|&jMj-}0|0s|(jDr0|j d|(jDd|j d |j |0|j d |r'|j.rt5|| \}"}#g}$tO||D]\}1}2tQ|1|$|"|#|2s|j d |r||1gzn||1g}3|r|}4n | r|s|d z }4n|}4tS|1|"|#\}5}6| xr"| xr|duxrt|d k(xr|1|dk(}7| xr1| xr-|duxr't|d k(xr|djU|1dz}8|2j||2g5tW|2|||4||3d||5|6|8| |7xs|8| }9ddd|j 9ddl,}:dj |};|:j[d!d"|;};|;S#1swY}xYwcc})w#1swYXxYw)#aGenerate reStructuredText documentation for a CLI application. Parameters ---------- app : App The cyclopts App instance to document. recursive : bool If True, generate documentation for all subcommands recursively. Default is True. include_hidden : bool If True, include hidden commands/parameters in documentation. Default is False. heading_level : int Starting heading level for the main application title. Default is 1 (uses '=' markers). max_heading_level : int Maximum heading level to use. Headings deeper than this will be capped at this level. RST uses different underline characters for each level. Default is 6. command_chain : list[str] Internal parameter to track command hierarchy. Default is None. generate_toc : bool If True, generate a table of contents for multi-command apps. Default is True. flatten_commands : bool If True, generate all commands at the same heading level instead of nested. Default is False. commands_filter : list[str], optional If specified, only include commands in this list. Supports nested command paths like "db.migrate". Default is None (include all commands). exclude_commands : list[str], optional If specified, exclude commands in this list. Supports nested command paths like "db.migrate". Default is None (no exclusions). no_root_title : bool If True, skip generating the root application title. Useful when embedding in existing documentation with its own title. Default is False. skip_preamble : bool If True, skip the description and usage sections for the target command when filtering to a single command via ``commands_filter``. Useful when the user provides their own section introduction. Default is False. usage_name : str | None Optional replacement for the root app name used in ``Usage:`` lines only. Section headings, anchors, and TOC continue to use ``app.name[0]``. Default is None. Returns ------- str The generated RST documentation. r) RstFormatterNcyclopts /rz.. _:rr" help_formatrestructuredtext)fallbackF)preserve_markupz:: z )rXrstT)r.)rEr.commandz**z:**z`` parameterr.) rDr.rErFrGrHrIrJrKrLrMrNrOz\n{3,}z ).cyclopts.help.formatters.rstrQr extendr<r joinreplacer(minrr, app_stackresolverr isinstancestrrrsplitrstripr0rC_assemble_help_panelsr r4showformatr5r:r r@r descriptionresetcopy get_outputr rr startswithgenerate_rst_docsresub) primary_namedesc panel_copyoutputr2r3subcommand_chainnext_heading_levelsub_commands_filtersub_exclude_commandsis_single_targetis_intermediate_pathsubdocsrtdocs< rrsrssN: E )5c=)I&HlJ -b! K=1+<^\I0 u%    <<9 $*/--p-QL`adfgfmfmLnq-Op" 7k;UWr  ${{ r%++c23 R *16u{{1~" #E$5$5t< r,r23LL4v/ R *\\[ ( OO "-J dD* -))+113F;;LL2ekk]#!67LL$ V$ R k0nS]]B[ -C ?"$? ,S.ALD&)k#=?Z\b LL 9F}v5XW[L\ %2"}%2Q%6"%2"8U02M9 5 !5"!/!/#4//(A-/OA.. "!>!>#4/>(A->$A&11$*= !!!3-0+'#1"4&7"2!&%5$7%9"6%5"2"J6J)1" LL !qBv ))E C &&FC (C J[  8qp10s$,X:/'YYY :Y Y )T) TFr"r'NTFNNFFFN)__doc__typingrcyclopts._markuprcyclopts.docs.baserrrrr r r r r rr cyclopts.corerrhlistrintr,booldictr4setr@rCrsrrrrs? )    !ST#Y(#"3#"s#"tCy#"LE44U CS,( (c5j!(c(3x$ ( C4 (  (V c t  &*"(,)-"!D DDD D  D 9t# DDD#Y%D3i$&DDDDd D Dr