i7 dZddlZddlmZddlmZmZer ddlmZddl m Z ddl m Z ddl m Z mZd d d efd Zd d d efd Zd d ded efdZd d deed efdZ d0deedzdeedzd eeedzeedzffdZdedeedeedzdeedzdd d ef dZdedeedzdeedzd eeedzeedzffdZd1d d deedzd eeeeffdZdeedzdeded eefdZd ed efd!Zdedd d"d d#ed ef d$Zd d d%d&d#ed eefd'Zd d d(ed edzfd)Z d d d edzfd*Z!d2d+edeed,ed efd-Z"d3d d d#ed.efd/Z#y)4z,Base utilities for documentation generation.N)Sequence) TYPE_CHECKINGAny)App) HelpPanel) CommandSpec) format_doc format_usageapprreturncht|jjdk(}|ry|jduS)a|Determine if usage should be shown for an app. Root apps always show usage (even without default_command, showing "app COMMAND"). Subcommands only show usage if they have a default_command. This skips usage for command groups that can't be invoked directly. The determination is made by checking the app_stack depth: - Stack length of 1 means root app (just the initial frame) - Stack length > 1 means we're in a subcommand context (frames were pushed) Parameters ---------- app : App The App instance to check. Returns ------- bool True if usage should be shown. TN)len app_stackstackdefault_command)r is_roots x/home/jay/workspace/.worktrees/task-2116-dev1/scripts/.codegraph-venv/lib/python3.12/site-packages/cyclopts/docs/base.pyshould_show_usagers6,#--%%&!+G""$..c|jduS)aDetermine if commands list should be shown for an app. Only show commands list for apps with a default_command. Command groups (apps without default_command) skip the list since their commands will be documented recursively anyway. Parameters ---------- app : App The App instance to check. Returns ------- bool True if commands list should be shown. N)r)r s rshould_show_commands_listr/s"   d **rnamect|jjdd}t|jjdd}||z}||vS)aCheck if a flag name is a built-in help or version flag. Parameters ---------- app : App The App instance to check against. name : str The flag name to check. Returns ------- bool True if this is a built-in help or version flag. help_flags)fallback version_flags)setrresolve)r rrr builtin_flagss r_is_builtin_flagr"CsUS]]**<"*EFJ --o-KLM.M =  rnamesc2|sytfd|DS)a4Check if all names in the sequence are builtin help or version flags. Parameters ---------- app : App The App instance to check against. names : Sequence[str] Sequence of flag names to check. Returns ------- bool True if all names are builtin flags. Fc36K|]}t|ywN)r").0rr s r z'is_all_builtin_flags..is=tT*=s)all)r r#s` ris_all_builtin_flagsr*Xs  =u= ==rcommands_filterexclude_commandscd}||Dchc]}|jdd}}d}|r|Dchc]}|jdd}}||fScc}wcc}w)aNormalize command filter lists by converting underscores to dashes. Parameters ---------- commands_filter : list[str] | None List of commands to include. exclude_commands : list[str] | None List of commands to exclude. Returns ------- tuple[set[str] | None, set[str] | None] Normalized include and exclude sets for O(1) lookup. N_-)replace)r+r,normalized_includecmdnormalized_excludes rnormalize_command_filtersr4lso$"?NOckk#s3OO?OPckk#s3PP 1 11 PQs A A parent_pathnormalized_commands_filternormalized_exclude_commandssubappc|rdj||gzn|}|r?||vs||vrytt|D]}dj|d|dz}||vsy|u||vs||vrytt|D]}dj|d|dz}||vsyt|dr)|jr|D]}|j |dzsyyy)a3Determine if a command should be included based on filters. Parameters ---------- name : str The command name. parent_path : list[str] Path to parent commands. normalized_commands_filter : set[str] | None Set of commands to include (already normalized). normalized_exclude_commands : set[str] | None Set of commands to exclude (already normalized). subapp : App The subcommand App instance. Returns ------- bool True if the command should be included, False otherwise. .FNrT _commands)joinrangerhasattrr; startswith) rr5r6r7r8 full_pathiparent_segment filter_cmds rshould_include_commandrDs 63>v-.4I" . .)?Z2Zs;'( A XXk'AE&:;N!<<  "- - ->X1Xs;'( A XXk'AE&:;N!;;  6; 'F,<,<8 ((S9  rcd}|_g}|D]R}|j|dzr3|t|dzd}|j|jddJ||k(sPd}n||sg}d}|rqg}|D]j}|j|dzr3|t|dzd}|j|jddJ|j|jddl||fS)aAdjust filter lists for subcommand context. Parameters ---------- name : str The current command name. normalized_commands_filter : set[str] | None Set of commands to include (already normalized). normalized_exclude_commands : set[str] | None Set of commands to exclude (already normalized). Returns ------- tuple[list[str] | None, list[str] | None] Adjusted commands_filter and exclude_commands lists (denormalized). Nr:rr/r.)r?rappendr0) rr6r7sub_commands_filterrC sub_filtersub_exclude_commands exclude_cmd sub_excludes radjust_filters_for_subcommandrLs*!- 4 J$$TCZ0'D A 8 #**:+=+=c3+GHt#&*#    *3F"$ "!6 KK%%dSj1)#d)a-/: $++K,?,?S,IJ$++K,?,?S,IJ  K  4 44r command_chainch|s|jd}|}|}n|d}dj|}|}|||fS)a8Get app name, full command path, and title. Parameters ---------- app : App The cyclopts App instance. command_chain : Optional[List[str]] Chain of parent commands leading to this app. Returns ------- Tuple[str, str, str] (app_name, full_command, title) r )rr<)r rMapp_name full_commandtitles r get_app_inforSsH 88A;  #xx .  \5 ((r command_namerPc|r||gzS||gS)a>Build command chain for a subcommand. Parameters ---------- command_chain : Optional[List[str]] Current command chain. command_name : str Name of the subcommand. app_name : str Name of the root app. Returns ------- List[str] Updated command chain. r)rMrTrPs rbuild_command_chainrV s" ~--,''r command_pathct|jjdd}tjdd|}|S)afGenerate a URL-friendly anchor from a command path. Converts spaces to hyphens and lowercases the string to match how markdown/HTML processors generate anchors from headings. Strips leading dashes to match markdown processor behavior. Parameters ---------- command_path : str Full command path (e.g., "myapp files cp"). Returns ------- str Anchor string (e.g., "myapp-files-cp"). Examples -------- >>> generate_anchor("myapp files cp") 'myapp-files-cp' >>> generate_anchor("myapp --install-completion") 'myapp-install-completion' rOr/z-+)lowerr0resub)rWanchors rgenerate_anchorr]#s60   ! ) )#s 3F VVE3 'F Mr parent_appinclude_hiddencht||ryt|t|sy|s |jsyy)a|Check if a command should be skipped. Parameters ---------- command_name : str Name of the command. subapp : App The subcommand App instance. parent_app : App The parent App instance. include_hidden : bool Whether to include hidden commands. Returns ------- bool True if command should be skipped. TF)r" isinstancetypeshow)rTr8r^r_s rshould_skip_commandrdAs2& L1 fd:. / &++ rpanelrc|r |jS|jDcgc]'}|jrt||jr&|)c}Scc}w)aXFilter help panel entries based on visibility settings. Parameters ---------- app : App The App instance to check against. panel : HelpPanel The help panel to filter. include_hidden : bool Whether to include hidden entries. Returns ------- List[Any] Filtered panel entries. )entriesr#r*)r rer_es rfilter_help_entriesri`s@"}}}} ]!QWW9McSTSZSZ9[A ]] ]s 'A A  help_formatct||}|S)zExtract app description. Parameters ---------- app : App The App instance. help_format : str Help format type. Returns ------- Optional[Any] The extracted description object, or None. )r )r rj descriptions rextract_descriptionrmwsS+.K rcj|j|jr |jSdSt|g}|S)zExtract usage string. Parameters ---------- app : App The App instance. Returns ------- Optional[Any] The extracted usage object, or None. N)usager )r ros r extract_usagerps4 yyIIsyy/4/ b !E Lr usage_textprefixc|syd|vr |jddj}|rdj|nd}|jdd}t |dkDr+|r)|r |d|d|dn |d|d}|jS|r|r|d|n|}|jS|r|d|n|}|jS)aEFormat usage line with proper command path. Parameters ---------- usage_text : str Raw usage text. command_chain : List[str] Command chain for the app. prefix : str Optional prefix for the usage line (e.g., "$"). Returns ------- str Formatted usage line. zUsage:rONr)r0stripr<splitr)rqrMrrrQparts usage_lines rformat_usage_linerys" :''"5;;= .;388M*L   T1 %E 5zA~->Dxqaaz:\NZ[\abc\d[eJf     39xq/|     28xq -Z    r resolve_lazyc#K|jsyt}|jjD]\}}t||rt |t r!|j s|s2|j|}n|}t |t|s\|s |jskt|}||vr{|j|||fyw)aIterate through app commands, yielding valid resolved subapps. Automatically resolves CommandSpec instances to App instances. Each unique subapp is yielded only once (first occurrence wins). Parameters ---------- app : App The App instance. include_hidden : bool Whether to include hidden commands. resolve_lazy : bool If ``True`` (default), resolve lazy commands (import their modules) to include them in the output. If ``False``, skip unresolved lazy commands. Set to ``True`` when generating static artifacts that need all commands, such as documentation or shell completion scripts. Yields ------ Tuple[str, App] (command_name, resolved_subapp) for each valid command. N) r;ritemsr"rar is_resolvedr rbrcidadd)r r_rzseenr app_or_specr8app_ids riterate_commandsrs. ==UD ]]002k C &  k; /**< ((-F F&$s), fkk F T>  Fl/sCC )NNr&)rt)FT)$__doc__rZcollections.abcrtypingrr cyclopts.corer cyclopts.helprcyclopts.command_specrr r boolrrstrr"r*listtuplerr4rDrLrSrVr]rdrirmrpryrrrrrs2 $%!'-2/5/T/@+5+T+(!%!s!t!*>e>HSM>d>*)-)-2#Y%23i$&2 3s8d?CHtO +,2:5 5c5!$C45"%SD 5  5  5p-5 -5 #C4-5"%SD-5 49t T#Y- -. -5`)e)DI,<)cSVX[mH\)6(tCy4'7(s(VY(^bcf^g(.##<c5e]afj>^U^;^^QUVYQZ^.Ut&ut(!#!d3i!!VY!H3%33T3r