+
    "lis6  c                   s
   R t ^ RIHtHtHt ^ RIt^ RIt^ RIt^ RI	t	^ RI
t
^tR R ltR R ltR R ltR	 R
 ltRDR R lltRDR R lltRDR R lltRDR R lltR R ltR R ltR R ltR R ltR R ltRDR R lltR R  ltR! R" ltRER# R$ lltR% R& ltR' R( ltRDR) R* lltRDR+ R, llt R- R. lt!R/ R0 lt"R1 R2 lt#R3 R4 lt$R5 R6 lt%R7 R8 lt&R9 R: lt'R; R< lt(R= R> lt)R? R@ lt*RA RB lt+],RC8X  d
   ]+! 4        R# R# )Fa?  
Script to auto generate the documentation for Netlink specifications.

:copyright:  Copyright (C) 2023  Breno Leitao <leitao@debian.org>
:license:    GPL Version 2, June 1991 see linux/COPYING for details.

This script performs extensive parsing to the Linux kernel's netlink YAML
spec files, in an effort to avoid needing to heavily mark up the original
YAML file.

This code is split in three big parts:
    1) RST formatters: Use to convert a string to a RST output
    2) Parser helpers: Functions to parse the YAML data structure
    3) Main function and small helpers
)AnyDictListNc                0    V ^8  d   QhR\         R\        /# )   levelreturnintstrZformat   "6/usr/lib/python3.14/site-packages/pyynl/ynl_gen_rst.py__annotate__r   "   s     + +C +C +    c                s*    RV \         ,          ,          # )zReturn space to format )SPACE_PER_LEVELr      &r   headroomr   "   s    %/)**r   c                0    V ^8  d   QhR\         R\         /# r   textr   r	   r
   r   r   r   r   '   s      s s r   c                    RV  R2# )zFormat bold textz** r   r   r   boldr   '       vR=r   c                r   r   r   r
   r   r   r   r   ,   s        r   c                r   )zFormat inline textz``r   r   r   r   inliner   ,   r   r   c                r   r   r   r
   r   r   r   r   1   s     0 03 03 0r   c                sT    \        V 4      P                  RR4      P                  4       # )z#Remove newlines and multiple spaces
r   )r	   replaceZstripr   r   r   sanitizer    1   s$     t9T3'--//r   c                sH    V ^8  d   QhR\         R\         R\        R\         /# r   keyvaluer   r   r	   r   r
   r   r   r   r   7   s(     0 0C 0 0C 0 0r   c                s2    \        V4      RV  RV 2,           # )zReturn a RST formatted fieldZ:z: r   r"   r#   r      &&&r   
rst_fieldsr(   7   s    E?qRw///r   c                sH    V ^8  d   QhR\         R\        R\        R\         /# r!   )r	   r    r   r
   r   r   r   r   <   s.     K K KC K KC Kr   c                s    \        V4      V ,           R,           \        V^,           4      ,           \        V4      ,           # )zFormat a single rst definitionr   )r   r	   r&   r'   r   rst_definitionr)   <   s-    E?S 4'(519*==E
JJr   c                <    V ^8  d   QhR\         R\        R\         /# )r   	paragraphr   r   r$   r
   r   r   r   r   A   s!     ' 'S ' 'S 'r   c                s&    \        V4      V ,           # )zReturn a formatted paragraphr%   )r+   r      &&r   rst_paragraphr-   A   s    E?Y&&r   c                r*   )r   itemr   r   r$   r
   r   r   r   r   F   s!     ) )S ) )S )r   c                s,    \        V4      RV  2,           # )zReturn a formatted a bulletz- r%   )r.   r   r,   r   
rst_bulletr/   F   s    E?r$[((r   c                r   r   titler   r   r
   r   r   r   r   K   s     + +# +# +r   c                :    V  R2R\        V 4      ,          ,           # )z!Add a sub-section to the documentr   -Zlenr1   r   r   rst_subsectionr6   K       WB<#E
***r   c                r   r0   r   r
   r   r   r   r   P   s     + +S +S +r   c                r2   )z%Add a sub-sub-section to the documentr   Z~r4   r5   r   r   rst_subsubsectionr8   P   r7   r   c                H    V ^8  d   QhR\         R\         R\         R\         /# )r   	namespaceprefixr1   r   r   r
   r   r   r   r   U   s.     P P3 P PC PC Pr   c           	     sN    RV  RV RV RV R2	R\        V4      ,          ,           # )zAdd a section to the document.. _r3   :

r   =r4   )r:   r;   r1   r'   r   rst_sectionr?   U   s1    )AfXQugU5'<sSZ?OOOr   c                r   r0   r   r
   r   r   r   r   Z   s     P P P Pr   c                s    RR\        V 4      ,          ,           RV  R2,           R\        V 4      ,          ,           R,           # )zAdd a subtitle to the documentr   r3   

r4   r5   r   r   rst_subtitlerA   Z   s6    #E
""r%^3cCJ6FFOOr   c                r   r0   r   r
   r   r   r   r   _   s     I IS IS Ir   c                sx    R\        V 4      ,          RV  R2,           R\        V 4      ,          ,           R,           # )zAdd a title to the documentr>   r   r@   r4   r5   r   r   	rst_titlerB   _   s1    U5'n,sSZ/??&HHr   c                sR    V ^8  d   QhR\         \        ,          R\        R\        /# )r   list_r   r   )r   r	   r   r
   r   r   r   r   d   s*     M M49 MS M Mr   c                sn    \        V4      R,           RP                  R V  4       4      ,           R,           # )zFormat a list using inlinesZ[z, c              3   s8   "   T F  p\        V4      x  K  	  R # 5i)N)r   )Z.0Zi   & r   Z	<genexpr>Z"rst_list_inline.<locals>.<genexpr>f   s     ,F1VAYYs   Z])r   join)rC   r   r,   r   rst_list_inlinerF   d   s*    E?S 499,F,F#FFLLr   c                r9   )r   r:   r;   namer   r   r
   r   r   r   r   i   s(     1 1s 1C 1s 1s 1r   c                sJ    RRRRRRRR/pW9   d	   W1,          pRV  RV RV R	2# )
zAdd a hyperlink to the documentenum
definitionfixed-headernested-attributesattribute-setstructz:ref:`r3   Z`r   )r:   r;   rG   Zmappingss   &&& r   rst_refrN   i   sH    #_,(H !I;axqa00r   c                s$    V ^8  d   QhR\         /# r   r   r   r
   r   r   r   r   t   s      C r   c                 s    . p V P                  \        R4      4       V P                  \        R4      4       RP                  V 4      # )z0The headers for all the auto generated RST filesz#.. SPDX-License-Identifier: GPL-2.0z,.. NOTE: This document was auto-generated.

r   )appendr-   rE   )liness    r   
rst_headerrR   t   s:    E	LLDEF	LLOPQ99Ur   c                r   )r   maxdepthr   r   r
   r   r   r   r   ~   s      # c r   c                st    . pVP                  R4       VP                  RV  R24       RP                  V4      # )z Generate a toctree RST primitivez.. toctree::z   :maxdepth: r@   r   )rP   rE   )rS   rQ   rD   r   rst_toctreerT   ~   s7    E	LL 	LL>(40199Ur   c                r   r0   r   r
   r   r   r   r      s      S S r   c                s    RV  R2# )zReturn a formatted labelr<   r=   r   r5   r   r   	rst_labelrU      s    %r   c                sh    V ^8  d   QhR\         \        \        \        3,          ,          R\        /# )r   mcast_groupr   r   r   r	   r    r
   r   r   r   r      s'      4S#X#7 C r   c                s|    . pV  F$  pVP                  \        VR,          4      4       K&  	  RP                  V4      # )z:Parse 'multicast' group list and return a formatted stringrG   r   )rP   r/   rE   )rV   rQ   groups   &  r   parse_mcast_grouprY      s7    EZf./  99Ur   c                ^    V ^8  d   QhR\         \        \        3,          R\        R\        /# )r   do_dictr   r   r   r	   r    r   r
   r   r   r   r      s)     
 
d38n 
S 
 
r   c                s   . pV P                  4        F  pVP                  \        \        V4      V^,           4      4       VR9   d2   VP                  \	        W,          V^,           4      R,           4       Kf  VP                  \        V^,           4      W,          ,           R,           4       K  	  RP                  V4      # )z0Parse 'do' section and return a formatted stringr   )ZrequestZreply)keysrP   r-   r   parse_do_attributesr   rE   )r[   r   rQ   r"   s   &&  r   parse_dor_      s    E||~]49eai89&&LL,W\519ELMLL%!),w|;dBC  99Ur   c                rZ   )r   attrsr   r   r\   r
   r   r   r   r      s)      tCH~ c # r   c                s    RV 9  d   R# \        R\        V R,          4      V^,           4      .pRP                  V4      # )zParse 'attributes' section
attributes r   )r(   rF   rE   )r`   r   rQ      && r   r^   r^      s<    5 oeL6I&JETUIVWE99Ur   c                t    V ^8  d   QhR\         \        \        \        3,          ,          R\        R\        /# )r   
operationsr:   r   rW   r
   r   r   r   r      s.      d38n!5 # # r   c           
     s"   . ROpRR.p. pV  EFn  pVP                  \        VRVR,          4      4       VP                  \        VR,          4      R	,           4       VP                  4        F@  pWb9   d   K  WV,          pWc9   d   \	        WV4      pVP                  \        Wg^ 4      4       KB  	  RV9   d,   VP                  \        R\        VR,          4      4      4       RV9   d>   VP                  \        R
^ 4      4       VP                  \        VR,          ^ 4      4       RV9   d>   VP                  \        R^ 4      4       VP                  \        VR,          ^ 4      4       VP                  R	4       EKq  	  R	P                  V4      # )zParse operations blockrG   docdodumpflagsrJ   rL   	operationr   z:do:z:dump:)rG   rf   r1   rg   rh   ri   )	rP   r?   r-   r]   rN   r(   rF   r_   rE   )re   r:   preprocessedlinkablerQ   rj   r"   r#   s   &&      r   parse_operationsrm      sE   BL0HE	[K69JKL]9U#34t;<>>#C"NE	6LLC23 $ iLLG_Yw=O-PQR9LLvq12LL)D/156YLLx34LL)F"3Q78 	T/  2 99Ur   c                st    V ^8  d   QhR\         \        \        \        3,          ,          R\        R\        /# )r   entriesr   r   )r   r   r	   r    r   r
   r   r   r   r      s.      4S#X/   r   c                sL   R.p. pV  F  p\        V\        4      '       d   VP                  RR4      pWR9   d   K3  VP                  R4      pV'       d   VR\        V4       R2,          pVP	                  \        V\        VP                  RR4      4      V4      4       K  \        V\        4      '       d   VP	                  \        WA4      4       K  VP	                  \        \        \        V4      4      V4      4       K  	  VP	                  R4       RP                  V4      # )	zParse a list of entriesZpadrG   rb   type ()rf   r   )Z
isinstanceZdictgetr   rP   r(   r    listrF   r/   rE   )rn   r   ignoredrQ   entryZ
field_nametype_   &&     r   parse_entriesrx      s    gGEeT""62.J$IIf%E6%=/33
LL:x		%0D'EuM t$$LL67LLF8E?$;UCD " 
LL99Ur   c                s^    V ^8  d   QhR\         \        \        3,          R\        R\        /# )r   defsr:   r   r   r	   r    r
   r   r   r   r      s)      DcN s s r   c                sj   . R	OpR.p. pV  EF  pVP                  \        VRVR,          4      4       VP                  4        F=  pWbV,           9   d   K  VP                  \        V\	        WV,          4      ^ 4      4       K?  	  VP                  R4       RV9   d>   VP                  \        R^ 4      4       VP                  \        VR,          ^4      4       RV9   g   K  VP                  \        R^ 4      4       VP                  \        VR,          ^4      4       EK  	  RP                  V4      # )
zParse definitions sectionrG   rn   membersz
render-maxrI   r   z	:entries:z	:members:)rG   rn   r{   )rP   r?   r]   r(   r    r-   rx   rE   )ry   r:   rk   rt   rQ   rI   krw   r   parse_definitionsr}      s    1LnGE
[L*V:LMN"A7**LLAx
'>BC # 	T
"LL{A67LLz)'<a@A
"LL{A67LLz)'<a@A   99Ur   c                rd   r   rn   r:   r   rW   r
   r   r   r   r     s.      T$sCx.1 c c r   c           
     sV   RR.p. R	OpR.p. pV  EF  pVP                  \        VRVR,          4      4       VR,           F  pVP                  R4      pVR,          p	V'       d   V	R\        V4       R2,          p	VP                  \	        V	4      4       VP                  4        FW  p
WV,           9   d   K  W9   d   \        WWz,          4      pM\        Wz,          4      pVP                  \        W^ 4      4       KY  	  VP                  R4       K  	  EK  	  RP                  V4      # )
z"Parse attribute from attribute-setrG   ro   ZchecksrL   ra   rp   rq   r   )rH   rK   rM   sub-message)
rP   r?   rr   r   r8   r]   rN   r    r(   rE   )rn   r:   rk   rl   rt   rQ   ru   attrrv   Z	attr_liner|   r#   s   &&          r   parse_attr_setsr     s   F#LEHjGE[OU6]KL,''DHHV$EVIr&-22	LL*956YY[w..=#I$':E$TW-EZ!45 ! LL# ( * 99Ur   c                rd   r~   rW   r
   r   r   r   r   #  s.      T#s(^ 4   r   c                s   . pV  F  pVP                  \        VRVR,          4      4       VR,           F}  pVR,          pVP                  \        \        V4      4      4       R F7  pWd9   g   K  VP                  \	        V\        WWF,          4      ^4      4       K9  	  VP                  R4       K  	  K  	  RP                  V4      # )zParse sub-message definitionsr   rG   Zformatsr#   r   )rJ   rL   )rP   r?   r/   r   r(   rN   rE   )rn   r:   rQ   ru   Zfmtr#   r   rw   r   parse_sub_messagesr   #  s    E[M5=IJ##CLELLDK019;LLD,3ISY,O,-"/ 0 :
 LL $  99Ur   c                sR    V ^8  d   QhR\         \        \        3,          R\        /# )r   objr   rz   r
   r   r   r   r   7  s"     + +DcN +s +r   c                s   . pVP                  \        4       4       V R,          pRV R2pVP                  \        V4      4       VP                  \        R4      4       RV 9   d=   VP                  \	        R4      4       VP                  \        V R,          ^ 4      4       RV 9   dD   VP                  \	        R4      4       VP                  \        V R,          R	,          V4      4       R
V 9   dC   VP                  \	        R4      4       VP                  \        V R
,          R	,          4      4       RV 9   d=   VP                  \	        R4      4       VP                  \        V R,          V4      4       RV 9   d=   VP                  \	        R4      4       VP                  \        V R,          V4      4       RV 9   d=   VP                  \	        R4      4       VP                  \        V R,          V4      4       RP                  V4      # )z'Format the whole YAML into a RST stringrG   z	Family ``z`` netlink specificationz.. contents:: :depth: 3
rf   ZSummaryre   Z
Operationsrs   zmcast-groupszMulticast groupsZdefinitionsZDefinitionszattribute-setszAttribute setszsub-messageszSub-messagesr   )rP   rR   rB   r-   rA   rm   rY   r}   r   r   rE   )r   rQ   Zfamilyr1      &   r   
parse_yamlr   7  s   E 
LL[Fx78E	LL5!"	LL:;<|\),-]3u:q12 s\,/0%c,&7&?HI \"456&s>':6'BCD \-01&s='96BC 3\"234_S)9%:FCD \.12'N(;VDE99Ur   c                s8    V ^8  d   QhR\         P                  /# rO   )argparseZ	Namespacer
   r   r   r   r   i  s      ++ r   c                 s   \         P                  ! RR7      p V P                  RRRR7       V P                  RRR	R
7       V P                  4       pVP                  RRRRR7       VP                  RRRR
7       V P	                  4       pVP
                  '       d&   \        P                  ! \        P                  R7       VP                  '       dg   \        P                  P                  VP                  4      '       g8   \        P                  ! RVP                  4       \        P                  ! R4       VP                   '       g-   \        P"                  ! R4       \        P                  ! R4       \        P                  P                  VP                   4      '       d"   \        P$                  ! RVP                   4       V# )zParse arguments from userzNetlink RST generator)Zdescriptionz-vz	--verboseZ
store_true)actionz-oz--outputzOutput file name)helpz-xz--indexzGenerate the index page)r   r   z-iz--inputzYAML file namer   z%s is not a valid file.zNo output file specified.z"%s already exists. Overwriting it.)r   ZArgumentParserZadd_argumentZadd_mutually_exclusive_groupZ
parse_argsZverboseloggingZbasicConfigZDEBUGinputospathZisfilewarningsysexitoutputZerrordebug)ZparserrX   args      r   parse_argumentsr   i  s9   $$1HIF
k,?
j/AB //1E	i3L   
tY-=>D|||'--0zzz"''..4414::>;;;12	ww~~dkk"":DKKHKr   c                r   )r   filenamer   r   r
   r   r   r   r     s      c c r   c                s    \        V RRR7      ;_uu_ 4       p\        P                  ! V4      p\        V4      pRRR4       V#   + '       g   i     X# ; i)zETransform the YAML specified by filename into an RST-formatted stringZrutf-8ZencodingN)openyamlZ	safe_loadr   )r   Z	spec_fileZ	yaml_datacontentr   r   parse_yaml_filer     sG    	hg	.	.)NN9-	Y' 
/ N	 
/	. Ns   "AA	c                s4    V ^8  d   QhR\         R\         RR/# )r   r   r   r   Nr   r
   r   r   r   r     s!        c  S  T  r   c                s    \         P                  ! RV4       \        VRRR7      ;_uu_ 4       pVP                  V 4       RRR4       R#   + '       g   i     R# ; i)z,Write the generated content into an RST filezSaving RST file to %sZwr   r   N)r   r   r   Zwrite)r   r   Zrst_filerc   r   write_to_rstfiler     s=    MM)84	hg	.	.(w 
/	.	.	.s   A

A	c                s(    V ^8  d   QhR\         RR/# )r   r   r   Nr   r
   r   r   r   r     s     - -C -D -r   c                s~   . pVP                  \        4       4       VP                  \        R4      4       VP                  \        R4      4       VP                  \	        ^4      4       \
        P                  P                  V 4      p\        P                  ! RV4       \        \
        P                  ! V4      4       FH  pVP                  R4      '       d   VR8X  d   K#  VP                  RVP                  RR4       R24       KJ  	  \        P                  ! R	V 4       \        RP                  V4      V 4       R
# )zBGenerate the `networking_spec/index` content and write to the fileZspecszNetlink Family SpecificationszLooking for .rst files in %sz.rstz	index.rstz   rb   r   zWriting an index file at %sN)rP   rR   rU   rB   rT   r   r   Zdirnamer   r   ZsortedZlistdirZendswithr   r   rE   )r   rQ   Z	index_dirr   r   r   generate_main_index_rstr     s    E	LL	LL7#$	LL:;<	LLQ 'IMM0)<2::i01  ((H,Cs8++FB78;< 2
 MM/8RWWU^V,r   c                s    V ^8  d   QhRR/# )r   r   Nr   r
   r   r   r   r     s     - -d -r   c                 s.   \        4       p V P                  '       dk   \        P                  ! RV P                  4        \	        \
        P                  P                  V P                  4      4      p\        XV P                  4       V P                  '       d   \        V P                  4       R# R#   \         dX   p\        P                  ! RT P                  4       \        P                  ! T4       \        P                  ! R4        Rp?LRp?ii ; i)zCMain function that reads the YAML files and generates the RST filesz
Parsing %szFailed to parse %s.Nr   )r   r   r   r   r   r   r   rE   Z	Exceptionr   r   r   r   r   Zindexr   )r   r   Z	exceptionr   r   mainr     s     DzzzlDJJ/	%bggll4::&>?G 	$++.zzz,   	OO14::>OOI&HHRLL	s   2B2 2D=ADDZ__main__)i    )r   )-Z__doc__Ztypingr    r   r   Zos.pathr   r   r   r   r   r   r   r   r   r    r(   r)   r-   r/   r6   r8   r?   rA   rB   rF   rN   rR   rT   rU   rY   r_   r^   rm   rx   r}   r   r   r   r   r   r   r   r   Z__name__r   r   r   <module>r      s   
  # "  
    
+


00
K
'
)
+
+
P
P
I
M
1
D22>(+dB -(-* zF r   