i@dZddlmZddlmZddlmZmZmZm Z m Z m Z m Z m Z mZmZerddlmZdedeefdZded edeefd Zd$d d d edeed ffdZdedeed fdeedeedzdeedzdef dZdeeddfdZ d%d d ded edededeedzdededeedzdeedzd ed!ed"edefd#Zy)&z9RST documentation generation functions for cyclopts apps.) TYPE_CHECKING) extract_text) adjust_filters_for_subcommandextract_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 w/home/jay/workspace/.worktrees/task-2116-dev1/scripts/.codegraph-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_mapr3Qs:K }},S.A 'LD& &K  ' rentriesr0 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 ) r4r0r5r6r7filtered_entriesentrycmd_namer2s r_filter_command_entriesr?gs6 3 ;;{{1~H __X.F~$,1C1K$++E2*(KARTfhno$++E2 3 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;)r@s r _generate_tocrBs5  LL23 LL LL  LLr recursive heading_levelmax_heading_level command_chain generate_tocflatten_commandscommands_filterexclude_commands no_root_titlecode_block_title skip_preamblec  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}|rnt!|t"r|}nt%|dd}|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 t/||j|g5|j1g|}dddt3|| \} }!g}"t5|d}#| |d z|}$D]\}%}&|s|%r |%j6s| r|s|&j8dk(r|&j:D'cgc]'}'|'j<rt?||'j<r&|')}(}'|(sltA|(|#|"| |!})|)s~|&jBr0|j d|&jBd|j d |)D]q}*|*j<r|*j<dnd }+t%|*jDd},|j d|+d|,r|j d|,|j d s2|&j8dk(sC|$jG|&jId }-|$dd|-|$jKj+}.|.s|&jBr0|j d|&jBd|j d |j |.|j d |r&|j,rt3|| \} }!g}"tM||D]\}/}0tO|/|"| |!|0s|j d |r||/gzn||/g}1|r|}2n | r|s|d z }2n|}2tQ|/| |!\}3}4| xr"| xr|duxrt|d k(xr|/|dk(}5| xr1| xr-|duxr't|d k(xr|djS|/dz}6|0j||0g5tU|0|||2||1d||3|4|6| |5xs|6 }7ddd|j 7ddl+}8dj |}9|8jYd!d"|9}9|9S#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. Returns ------- str The generated RST documentation. r) RstFormatterNcyclopts /rz.. _:rr! help_formatrestructuredtext)fallbackF)preserve_markupz:: z )rVrstT)r-)rDr-commandz**z:**z`` parameterr.) rCr-rDrErFrGrHrIrJrKrLrMz\n{3,}z )-cyclopts.help.formatters.rstrOr extendr;rjoinreplacer'minrr+ app_stackresolverr isinstancestrrsplitrstripr/rB_assemble_help_panelsr r3showformatr4r9r r?r descriptionresetcopy get_outputr r r startswithgenerate_rst_docsresub):r,rCr-rDrErFrGrHrIrJrKrLrMrOr@app_name full_command base_titler anchor_parts anchor_nameeffective_heading_level header_linesrUusage usage_textpartslinerlpreserve desc_texthelp_panels_with_groupsnormalized_commands_filternormalized_exclude_commandsr5r0 formattergrouppanelecommand_entriesr<r= primary_namedesc panel_copyoutputr1r2subcommand_chainnext_heading_levelsub_commands_filtersub_exclude_commandsis_single_targetis_intermediate_pathsubdocsrrdocs: rrqrqsD: E )5c=)I&HlJ -b! K=1+<^\I05! u%    <<9 $*/--pQL`adfgfmfmLnqpOp" 7k;UWr  ${{ r%++c23 R * !16u{{1~" #E$5$5t< r,r23LL4v/ R  !\\[ ( OO "-J dD* -))+113F;;LL2ekk]#!67LL$ V$ R k5!nS]]B[ -C ?"$? ,S.A7 "LD&)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  LL !o7 "t ))E C &&FC (C JYMM8qp  s$ X-#'X: X: X?-X7?Y )T) TFr!r&NTFNNFFF)__doc__typingrcyclopts._markuprcyclopts.docs.baserrrrr r r r r r cyclopts.corerrflistrintr+booldictr3setr?rBrqrrrrs? )   !ST#Y(#"3#"s#"tCy#"LE44U CS,( (c5j!(c(3x$ ( C4 (  (V c t  &*"(,)-"y yyy y  y 9t# yyy#Y%y3i$&yyyy yr