lKjydZddlmZddlmZddlmZddlmZm Z m Z m Z m Z m Z mZmZmZmZmZmZmZmZerddlmZ d/dd d ed ed eedzd eedzdeedzdedeeed ffdZdeedeeed fddfdZd0dd d edeed ffdZd0deedededdfdZdd dedeeddfdZ d1dd deedeededzddf dZ!dd ded ed eedzd eedzdedeeddfdZ"deeddfd Z#d!ed"eed fdeed#e$edzd$e$edzdef d%Z% d2dd d&ed ed'e&d(e&deedzd)ed*ed eedzd eedzd+ed,ed-ededzdefd.Z'y)3z5Documentation generation functions for cyclopts apps.) TYPE_CHECKING) extract_text)DEFAULT_FORMAT)adjust_filters_for_subcommandapply_usage_namebuild_command_chainextract_description extract_usageformat_usage_linegenerate_anchor get_app_infois_all_builtin_flagsiterate_commandsnormalize_command_filtersshould_include_commandshould_show_commands_listshould_show_usage)AppNapprinclude_hiddenprefixcommands_filterexclude_commands parent_pathskip_filtered_commandreturnc 6g}|g}t||\}} t||D]t\} } t| ||| | s|xr | j} | s|r|| n| } |j | | f|| gz}|| d}t | |||||d}|j |v|S)zoRecursively collect all commands for table of contents. Returns a list of (display_name, app) tuples.  F)rrrrrr)rrr _commandsappend_collect_commands_for_tocextend)rrrrrrrcommandsnormalized_commands_filternormalized_exclude_commandsnamesubappskip_this_command display_name nested_path nested_prefixnesteds g/Users/ahmed/devFolder/Ultron/claude-voice/.venv/lib/python3.12/site-packages/cyclopts/docs/markdown.pyr!r!sH >W)?; ;)n= f% +9;VX^  2Ff6F6F 06fXdV,DL OO\62 3"TF* !(4&* * ) +-#"'  7>: Olinesr#c i}|D]w\}}|jddz }d|z}|jd}t|}||vr||xxdz cc<|d||}nd||<|j|d|d|d yy ) zGenerate TOC entries with proper indentation. Parameters ---------- lines : list[str] List to append TOC entries to. commands : list[tuple[str, "App"]] List of (display_name, app) tuples. rz _rz- [``](#)N)countsplitr r ) r/r# anchor_countsr)_appdepthindentcmd_nameanchors r-_generate_toc_entriesr>Rs%'M& d""3'!+%%%'+ . ] " & !Q & !xqv!6 78F$%M& ! xtH:T&;<'r.cTi}|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. )rr)rr command_mapr&r's r-_build_command_maprAns6K }},S.ALD& &K B r.content add_blankcR|r|j||r|jdyy)aAppend content to lines if present, optionally adding blank line. Parameters ---------- lines : list[str] List to append to. content : str Content to append (only if non-empty). add_blank : bool Whether to add a blank line after content. N)r )r/rBrCs r-_append_if_presentrFs' W Rr. help_formatct||}|rF|dv}t|d|}|r1|j|j|jdyyy)aExtract and render app description. Parameters ---------- app : App The app to extract description from. help_format : str Help format (e.g., "markdown", "rich"). lines : list[str] List to append description to. markdownmdNpreserve_markuprE)r rr strip)rrGr/ descriptionpreserve desc_texts r-_render_description_sectionrRsX&c;7K"44 dHM  LL* + LL   r. command_chain usage_namec2t|rt|}|r~|jdt|tr|}nt |dd}t ||}t||}|j||jd|jdyyy)aSRender usage console block. Parameters ---------- app : App The app to extract usage from. command_chain : list[str] Command chain for usage line. lines : list[str] List to append usage to. usage_name : str | None Optional replacement for the chain's root in Usage: lines only. z ```consoleNFrLz```rE)rr r isinstancestrrrr )rrSr/rTusage usage_text display_chain usage_lines r-_render_usage_sectionr\s&c"  LL &%%" )%uM ,]JGM*:}EJ LL $ LL  LL  r.app_namect|||r|dnd|||}|r@|jd|jdt|||jdyy)aGenerate and render table of contents. Parameters ---------- app : App The app to generate TOC for. app_name : str Application name for TOC prefixes. include_hidden : bool Whether to include hidden commands. commands_filter : list[str] | None Commands to include. exclude_commands : list[str] | None Commands to exclude. skip_filtered_command : bool Whether to skip the single filtered command in TOC. lines : list[str] List to append TOC to. rrE)rrrrrz## Table of ContentsN)r!r r>)rr]rrrrr/ toc_commandss r- _render_tocr`sc:- %!)(1~r')3 L +, Re\2 R r.c8|j|jd}|dd||jj}|rN|jr|j d|jd|j ||j dyy)a Render a parameter panel as-is. Parameters ---------- panel : HelpPanel The parameter panel to render. formatter : MarkdownFormatter Formatter to use for rendering. lines : list[str] List to append rendered content to. rE)titleN****: )resetcopy get_outputrNrbr )panel formatterr/ panel_copyoutputs r-_render_parameter_panelrlsOO"%J dD*%  ! ! # ) ) +F ;; LL2ekk]%0 1 V R r.entriesr@normalized_filternormalized_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)namesgetr r) rmr@rrnrofiltered_entriesentryr<r's r-_filter_command_entriesrus6 ;;{{1~H __X.F~$,1C1K$++E2*(KARTfhno$++E2 r. recursive heading_levelmax_heading_level generate_tocflatten_commands no_root_titlecode_block_title skip_preamblecddlm}g}|g}d}nd}|xr|duxrt|dk(}t||\}}}|r | rd|dn|}n|}|s:| r|s6t ||}|j d|zd ||j d |j jd t }|s| st|||| |s| s t||||r|s|jrt||||| |||s|j |g5|jg|}dddt|| \}}g}t|d}||dz|d}D]d\}}|s|r |j s|j"dk(r|j$D cgc]'} | j&rt)|| j&r&| )}!} |!sgt+|!||||}"|"sy|j,r|j d|j,d|"D]}#|#j&s|#j&d}$|d |$}%t/|%}&|#j0rt3|#j0ddnd }'|'r|j d|$d|&d|'t|j d|$d|&d|j d G|j"dk(sXt5|||gnt|| \}}g}|jrt7||D]\}(})t9|(||||)st;||(|}*|r|}+n | r|s|}+n|dz}+|duxrt|dk(},|,xr|duxr|(|dk(}-|,xr|duxr|dj=|(dz}.|xr|-}/| xr|xr|.}0| xr|-}1|/sS|0sQd j?|*}2| rd|2dn|2}3t |+|}4|j d|4zd |3|j d |1xs|0}5|)j ||)g5|)j jd | }6|6dv}7|5st|)|*|| t|)|6||r&|)jg|6}8tA|(||\}9}:t|9|:\};}|r|dz}?n|dz}?||?|d}@|xr |)j}A|8D]\}}|s|r |j s|j"dk(rstC|)rg|j$D cgc]'} | j&rt)|)| j&r&| )}B} |BssArg}!BD]}#|#j&s|#j&d}$|=jE|$}C|Crt9|$|>|;|<CsB|#j0rt3|#j0d|7nd }'d j?|*|$gz}%t/|%}&|'r|!j d|$d|&d|'|!j d|$d|&d|!s=|j,r|j d|j,d|jG|!|j d g}"BD]R}#|#j&s|#j&d}$|=jE|$}C|Crt9|$|>|;|<CsB|"j |#T|"s|j,r|j d|j,d@jI|jKd |"|j"|j0}D|@dd|D|@jMjO}E|Er|j E|j d |j"dk(st5|@||r1|)jr$tA|(||\}F}Gt|F|G\}H}Ig}Jt7|)|D]\}K}Lt9|KJHI|Lst;|*K|}M|r|}Nn |/r|+}Nn|+dz}NHrtAKHI\}O}Pnd}O| xrFduxrtFdk(xrKFdk(}Q| xr-Fduxr'tFdk(xrFdj=Kdz}RLj |)|Lg5tQL||N|Md|OGR| QxsR| }Sddd|j S|j d ddddj?|jSdz}Tddl*}U|UjWd d!|T}T|TS#1swYxYwcc} wcc} w#1swYxYw#1swYxYw)"auGenerate markdown 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 (single #). max_heading_level : int Maximum heading level to use. Headings deeper than this will be capped at this level. Standard Markdown supports levels 1-6. 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] | None 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] | None 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 the root application title. Used for plugin contexts. 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. Headings and TOC anchors still use ``app.name[0]``. Default is None (use ``app.name[0]`` as before). Returns ------- str The generated markdown documentation. r)MarkdownFormatterNTFr1`#rrErG)fallback)rT)rlist)rwr table_stylecommandrcrdrLz* [`r4z): r5 parameter.rI)rbrmformatrO) rvrrwrxrSryrzrrr{r|r}rT z\n{3,}z ),!cyclopts.help.formatters.markdownrlenr minr app_stackresolverr\rRrr`_assemble_help_panelsrrAshowrrmrqrrurbr rOrrlrrr startswithjoinrrrrr"re __class__rgrNgenerate_markdown_docsrstripresub)VrrvrrwrxrSryrzrrr{r|r}rTrr/is_rootskip_current_levelr] full_command base_titlerbeffective_levelrGhelp_panels_with_groupsr$r%rr@rigrouprhecommand_entriesrsrtr< full_cmd_pathr=rQr&r'sub_command_chainsub_heading_levelis_single_filteris_exact_targetis_intermediate_pathskip_this_command_titleskip_intermediateskip_target_preambler) display_fmteffective_sub_levelskip_this_preamblesub_help_format preserve_sub sub_panelssub_commands_filter_for_panelsub_exclude_commands_for_panelnormalized_sub_filter_panelnormalized_sub_exclude_panelsub_command_mapnested_parent_path_for_panelpanel_heading_level sub_formatter will_recursecommand_entries_list sub_cmd_appfiltered_panelrksub_commands_filtersub_exclude_commandsnormalized_sub_filternormalized_sub_excludenested_parent_path nested_name nested_appnested_command_chainnested_heading_levelnested_commands_filterr3nested_is_targetnested_is_intermediate nested_docsdocrsV r-rr?s LD E !^_D%@^SEY]^E^*6c=)I&HlJ'7!L>#\ }m->? o-.aw78 R--'' 'OK mc=%JO m#Ce<McmmC>?DTVhjop  ]]C5 !&)&?&?K&P #"C\ -C ?"$? )TB &'!+) 4LE5!eEJJ||y(/4mm"tmAGGPdehjkjqjqPr1m"t&$;#[+?Y[v$ ${{ r%++e%<="2 ;;',{{1~H0->VZ [vx& ) % tH:T&YK-X Y % tH:T&-K L"2LL$,'y%@S4XC\ -C ?"$?  }}-S.ALD&)k#=?Z\b!4M4 R  $1!}$1!$1A$5! /d:Xs??SWX?X .m?$3NmSW[jkl[mSmO n_D%@n_UVEWEbEbcgjmcmEn !'9&L_ # - ]2D ]I] #0#D_ +3D"xx(9: 5E,q1< &)*;=N&O# &9 9:!K=IJ R "6!J9J !!3-0"("2"2":":=S^":"_.2DD ))&2CUWab/O!'!=!=b/!RJUr8:UUQ13QQj57UQM/1M '9PT&UO460(.;a.?+.;a.?+$5&9.fl%M $-#A1A1AL)3 u-% $ <<949RSY9Z,1==4+8aMabhjkjqjqMr=14$8 ( ,24-AE',{{38;;q>6E6I6I(6S +6?U,4,H,G,H,7 @*-505/@/@-99J9JDbn,o13)2 9<ARV^U_A_8` 1@1O+4,;,B,BT(SWX^W__bclbmCn,o,;,B,BT(SWX^W__`Ca,b1.B4$3',{{(- r%++e5L(M$)LL$A$)LL$446 0-AE',{{38;;q>6E6I6I(6S +6?U,4,H,G,H,7 @*-5(8(?(?(F.B$4',{{(- r%++e5L(M$1$7$7$95:__.00@/4||494E4E 6E6&N %2$n$M-:-E-E-G-M-M-OF'-(- V(<$)LL$4"\\[83E=%Pi)3n!1!1@]8:UA=')=E^+-AEA)+A *,&3CFN3[/ Z5');=RTjlv %0CCTVack/l,+3@043D03Dq3H018U +-BDZ952A6:2 *F 34 ?F #$7 8A =F!,/B1/E E )*U 34 ?U #$7 8A =U!4A 6 A A+PSBS T /(116:2FG*@ **3/=.B2C.B-21A0F1E.D1A.>.XBX+5+KH$ [1 R(}4\a10gBH ))E  ! ! #d *C &&FC (C Jk " !8#uf4PHGw10sxb??'c 'c C/c" 'c 3c 7c"B1c"A"c")Ac"2Cc"5C:c"/c ,c"?c c"c c""c, )FrENNNF)T)N) TFr1NTFNNFFFN)(__doc__typingrcyclopts._markupr cyclopts.corercyclopts.docs.baserrrr r r r r rrrrrrrboolrWrtupler!r>dictrArFrRr\r`rlsetruintrr.r-rsf; )("! !(,)-$("'3 33 3#Y% 3 3i$& 3 cT! 3 3 %U 3l=c=d5e;L6M=RV=8E44U CS,d3i#$RV$UT#YSW4"  9 9d   D) )))#Y% ) 3i$& )  ) 9) )XT#Y44( (c5j!(c(3x$ ( C4 (  (Z &*"(,)-"!M MMM M  M 9t# MMM#Y%M3i$&MMMMd M Mr.