PNG  IHDRX cHRMz&u0`:pQ<bKGD pHYsodtIME MeqIDATxw]Wug^Qd˶ 6`!N:!@xI~)%7%@Bh&`lnjVF29gΨ4E$|>cɚ{gk= %,a KX%,a KX%,a KX%,a KX%,a KX%,a KX%, b` ǟzeאfp]<!SJmɤY޲ڿ,%c ~ع9VH.!Ͳz&QynֺTkRR.BLHi٪:l;@(!MԴ=žI,:o&N'Kù\vRmJ雵֫AWic H@" !: Cé||]k-Ha oݜ:y F())u]aG7*JV@J415p=sZH!=!DRʯvɱh~V\}v/GKY$n]"X"}t@ xS76^[bw4dsce)2dU0 CkMa-U5tvLƀ~mlMwfGE/-]7XAƟ`׮g ewxwC4\[~7@O-Q( a*XGƒ{ ՟}$_y3tĐƤatgvێi|K=uVyrŲlLӪuܿzwk$m87k( `múcE)"@rK( z4$D; 2kW=Xb$V[Ru819קR~qloѱDyįݎ*mxw]y5e4K@ЃI0A D@"BDk_)N\8͜9dz"fK0zɿvM /.:2O{ Nb=M=7>??Zuo32 DLD@D| &+֎C #B8ַ`bOb $D#ͮҪtx]%`ES`Ru[=¾!@Od37LJ0!OIR4m]GZRJu$‡c=%~s@6SKy?CeIh:[vR@Lh | (BhAMy=݃  G"'wzn޺~8ԽSh ~T*A:xR[ܹ?X[uKL_=fDȊ؂p0}7=D$Ekq!/t.*2ʼnDbŞ}DijYaȲ(""6HA;:LzxQ‘(SQQ}*PL*fc\s `/d'QXW, e`#kPGZuŞuO{{wm[&NBTiiI0bukcA9<4@SӊH*؎4U/'2U5.(9JuDfrޱtycU%j(:RUbArLֺN)udA':uGQN"-"Is.*+k@ `Ojs@yU/ H:l;@yyTn}_yw!VkRJ4P)~y#)r,D =ě"Q]ci'%HI4ZL0"MJy 8A{ aN<8D"1#IJi >XjX֔#@>-{vN!8tRݻ^)N_╗FJEk]CT՟ YP:_|H1@ CBk]yKYp|og?*dGvzنzӴzjֺNkC~AbZƷ`.H)=!QͷVTT(| u78y֮}|[8-Vjp%2JPk[}ԉaH8Wpqhwr:vWª<}l77_~{s۴V+RCģ%WRZ\AqHifɤL36: #F:p]Bq/z{0CU6ݳEv_^k7'>sq*+kH%a`0ԣisqにtү04gVgW΂iJiS'3w.w}l6MC2uԯ|>JF5`fV5m`Y**Db1FKNttu]4ccsQNnex/87+}xaUW9y>ͯ骵G{䩓Գ3+vU}~jJ.NFRD7<aJDB1#ҳgSb,+CS?/ VG J?|?,2#M9}B)MiE+G`-wo߫V`fio(}S^4e~V4bHOYb"b#E)dda:'?}׮4繏`{7Z"uny-?ǹ;0MKx{:_pÚmFמ:F " .LFQLG)Q8qN q¯¯3wOvxDb\. BKD9_NN &L:4D{mm o^tֽ:q!ƥ}K+<"m78N< ywsard5+Š²z~mnG)=}lYݧNj'QJS{S :UYS-952?&O-:W}(!6Mk4+>A>j+i|<<|;ر^߉=HE|V#F)Emm#}/"y GII웻Jі94+v뾧xu~5C95~ūH>c@덉pʃ1/4-A2G%7>m;–Y,cyyaln" ?ƻ!ʪ<{~h~i y.zZB̃/,雋SiC/JFMmBH&&FAbϓO^tubbb_hZ{_QZ-sύodFgO(6]TJA˯#`۶ɟ( %$&+V'~hiYy>922 Wp74Zkq+Ovn錄c>8~GqܲcWꂎz@"1A.}T)uiW4="jJ2W7mU/N0gcqܗOO}?9/wìXžΏ0 >֩(V^Rh32!Hj5`;O28؇2#ݕf3 ?sJd8NJ@7O0 b־?lldщ̡&|9C.8RTWwxWy46ah嘦mh٤&l zCy!PY?: CJyв]dm4ǜҐR޻RլhX{FƯanшQI@x' ao(kUUuxW_Ñ줮[w8 FRJ(8˼)_mQ _!RJhm=!cVmm ?sFOnll6Qk}alY}; "baӌ~M0w,Ggw2W:G/k2%R,_=u`WU R.9T"v,<\Ik޽/2110Ӿxc0gyC&Ny޽JҢrV6N ``یeA16"J³+Rj*;BϜkZPJaÍ<Jyw:NP8/D$ 011z֊Ⱳ3ι֘k1V_"h!JPIΣ'ɜ* aEAd:ݺ>y<}Lp&PlRfTb1]o .2EW\ͮ]38؋rTJsǏP@芎sF\> P^+dYJLbJ C-xϐn> ι$nj,;Ǖa FU *择|h ~izť3ᤓ`K'-f tL7JK+vf2)V'-sFuB4i+m+@My=O҈0"|Yxoj,3]:cо3 $#uŘ%Y"y죯LebqtҢVzq¼X)~>4L׶m~[1_k?kxֺQ`\ |ٛY4Ѯr!)N9{56(iNq}O()Em]=F&u?$HypWUeB\k]JɩSع9 Zqg4ZĊo oMcjZBU]B\TUd34ݝ~:7ڶSUsB0Z3srx 7`:5xcx !qZA!;%͚7&P H<WL!džOb5kF)xor^aujƍ7 Ǡ8/p^(L>ὴ-B,{ۇWzֺ^k]3\EE@7>lYBȝR.oHnXO/}sB|.i@ɥDB4tcm,@ӣgdtJ!lH$_vN166L__'Z)y&kH;:,Y7=J 9cG) V\hjiE;gya~%ks_nC~Er er)muuMg2;֫R)Md) ,¶ 2-wr#F7<-BBn~_(o=KO㭇[Xv eN_SMgSҐ BS헃D%g_N:/pe -wkG*9yYSZS.9cREL !k}<4_Xs#FmҶ:7R$i,fi!~' # !6/S6y@kZkZcX)%5V4P]VGYq%H1!;e1MV<!ϐHO021Dp= HMs~~a)ަu7G^];git!Frl]H/L$=AeUvZE4P\.,xi {-~p?2b#amXAHq)MWǾI_r`S Hz&|{ +ʖ_= (YS(_g0a03M`I&'9vl?MM+m~}*xT۲(fY*V4x@29s{DaY"toGNTO+xCAO~4Ϳ;p`Ѫ:>Ҵ7K 3}+0 387x\)a"/E>qpWB=1 ¨"MP(\xp߫́A3+J] n[ʼnӼaTbZUWb={~2ooKױӰp(CS\S筐R*JغV&&"FA}J>G֐p1ٸbk7 ŘH$JoN <8s^yk_[;gy-;߉DV{c B yce% aJhDȶ 2IdйIB/^n0tNtџdcKj4϶v~- CBcgqx9= PJ) dMsjpYB] GD4RDWX +h{y`,3ꊕ$`zj*N^TP4L:Iz9~6s) Ga:?y*J~?OrMwP\](21sZUD ?ܟQ5Q%ggW6QdO+\@ ̪X'GxN @'4=ˋ+*VwN ne_|(/BDfj5(Dq<*tNt1х!MV.C0 32b#?n0pzj#!38}޴o1KovCJ`8ŗ_"]] rDUy޲@ Ȗ-;xџ'^Y`zEd?0„ DAL18IS]VGq\4o !swV7ˣι%4FѮ~}6)OgS[~Q vcYbL!wG3 7띸*E Pql8=jT\꘿I(z<[6OrR8ºC~ډ]=rNl[g|v TMTղb-o}OrP^Q]<98S¤!k)G(Vkwyqyr޽Nv`N/e p/~NAOk \I:G6]4+K;j$R:Mi #*[AȚT,ʰ,;N{HZTGMoּy) ]%dHء9Պ䠬|<45,\=[bƟ8QXeB3- &dҩ^{>/86bXmZ]]yޚN[(WAHL$YAgDKp=5GHjU&99v簪C0vygln*P)9^͞}lMuiH!̍#DoRBn9l@ xA/_v=ȺT{7Yt2N"4!YN`ae >Q<XMydEB`VU}u]嫇.%e^ánE87Mu\t`cP=AD/G)sI"@MP;)]%fH9'FNsj1pVhY&9=0pfuJ&gޤx+k:!r˭wkl03׼Ku C &ѓYt{.O.zҏ z}/tf_wEp2gvX)GN#I ݭ߽v/ .& и(ZF{e"=V!{zW`, ]+LGz"(UJp|j( #V4, 8B 0 9OkRrlɱl94)'VH9=9W|>PS['G(*I1==C<5"Pg+x'K5EMd؞Af8lG ?D FtoB[je?{k3zQ vZ;%Ɠ,]E>KZ+T/ EJxOZ1i #T<@ I}q9/t'zi(EMqw`mYkU6;[t4DPeckeM;H}_g pMww}k6#H㶏+b8雡Sxp)&C $@'b,fPߑt$RbJ'vznuS ~8='72_`{q纶|Q)Xk}cPz9p7O:'|G~8wx(a 0QCko|0ASD>Ip=4Q, d|F8RcU"/KM opKle M3#i0c%<7׿p&pZq[TR"BpqauIp$ 8~Ĩ!8Սx\ւdT>>Z40ks7 z2IQ}ItԀ<-%S⍤};zIb$I 5K}Q͙D8UguWE$Jh )cu4N tZl+[]M4k8֦Zeq֮M7uIqG 1==tLtR,ƜSrHYt&QP윯Lg' I,3@P'}'R˪e/%-Auv·ñ\> vDJzlӾNv5:|K/Jb6KI9)Zh*ZAi`?S {aiVDԲuy5W7pWeQJk֤#5&V<̺@/GH?^τZL|IJNvI:'P=Ϛt"¨=cud S Q.Ki0 !cJy;LJR;G{BJy޺[^8fK6)=yʊ+(k|&xQ2`L?Ȓ2@Mf 0C`6-%pKpm')c$׻K5[J*U[/#hH!6acB JA _|uMvDyk y)6OPYjœ50VT K}cǻP[ $:]4MEA.y)|B)cf-A?(e|lɉ#P9V)[9t.EiQPDѠ3ϴ;E:+Օ t ȥ~|_N2,ZJLt4! %ա]u {+=p.GhNcŞQI?Nd'yeh n7zi1DB)1S | S#ًZs2|Ɛy$F SxeX{7Vl.Src3E℃Q>b6G ўYCmtկ~=K0f(=LrAS GN'ɹ9<\!a`)֕y[uՍ[09` 9 +57ts6}b4{oqd+J5fa/,97J#6yν99mRWxJyѡyu_TJc`~W>l^q#Ts#2"nD1%fS)FU w{ܯ R{ ˎ󅃏џDsZSQS;LV;7 Od1&1n$ N /.q3~eNɪ]E#oM~}v֯FڦwyZ=<<>Xo稯lfMFV6p02|*=tV!c~]fa5Y^Q_WN|Vs 0ҘދU97OI'N2'8N֭fgg-}V%y]U4 峧p*91#9U kCac_AFңĪy뚇Y_AiuYyTTYЗ-(!JFLt›17uTozc. S;7A&&<ԋ5y;Ro+:' *eYJkWR[@F %SHWP 72k4 qLd'J "zB6{AC0ƁA6U.'F3:Ȅ(9ΜL;D]m8ڥ9}dU "v!;*13Rg^fJyShyy5auA?ɩGHRjo^]׽S)Fm\toy 4WQS@mE#%5ʈfFYDX ~D5Ϡ9tE9So_aU4?Ѽm%&c{n>.KW1Tlb}:j uGi(JgcYj0qn+>) %\!4{LaJso d||u//P_y7iRJ߬nHOy) l+@$($VFIQ9%EeKʈU. ia&FY̒mZ=)+qqoQn >L!qCiDB;Y<%} OgBxB!ØuG)WG9y(Ą{_yesuZmZZey'Wg#C~1Cev@0D $a@˲(.._GimA:uyw֬%;@!JkQVM_Ow:P.s\)ot- ˹"`B,e CRtaEUP<0'}r3[>?G8xU~Nqu;Wm8\RIkբ^5@k+5(By'L&'gBJ3ݶ!/㮻w҅ yqPWUg<e"Qy*167΃sJ\oz]T*UQ<\FԎ`HaNmڜ6DysCask8wP8y9``GJ9lF\G g's Nn͵MLN֪u$| /|7=]O)6s !ĴAKh]q_ap $HH'\1jB^s\|- W1:=6lJBqjY^LsPk""`]w)󭃈,(HC ?䔨Y$Sʣ{4Z+0NvQkhol6C.婧/u]FwiVjZka&%6\F*Ny#8O,22+|Db~d ~Çwc N:FuuCe&oZ(l;@ee-+Wn`44AMK➝2BRՈt7g*1gph9N) *"TF*R(#'88pm=}X]u[i7bEc|\~EMn}P瘊J)K.0i1M6=7'_\kaZ(Th{K*GJyytw"IO-PWJk)..axӝ47"89Cc7ĐBiZx 7m!fy|ϿF9CbȩV 9V-՛^pV̌ɄS#Bv4-@]Vxt-Z, &ֺ*diؠ2^VXbs֔Ìl.jQ]Y[47gj=幽ex)A0ip׳ W2[ᎇhuE^~q흙L} #-b۸oFJ_QP3r6jr+"nfzRJTUqoaۍ /$d8Mx'ݓ= OՃ| )$2mcM*cЙj}f };n YG w0Ia!1Q.oYfr]DyISaP}"dIӗթO67jqR ҊƐƈaɤGG|h;t]䗖oSv|iZqX)oalv;۩meEJ\!8=$4QU4Xo&VEĊ YS^E#d,yX_> ۘ-e\ "Wa6uLĜZi`aD9.% w~mB(02G[6y.773a7 /=o7D)$Z 66 $bY^\CuP. (x'"J60׿Y:Oi;F{w佩b+\Yi`TDWa~|VH)8q/=9!g߆2Y)?ND)%?Ǐ`k/sn:;O299yB=a[Ng 3˲N}vLNy;*?x?~L&=xyӴ~}q{qE*IQ^^ͧvü{Huu=R|>JyUlZV, B~/YF!Y\u_ݼF{_C)LD]m {H 0ihhadd nUkf3oٺCvE\)QJi+֥@tDJkB$1!Đr0XQ|q?d2) Ӣ_}qv-< FŊ߫%roppVBwü~JidY4:}L6M7f٬F "?71<2#?Jyy4뷢<_a7_=Q E=S1И/9{+93֮E{ǂw{))?maÆm(uLE#lïZ  ~d];+]h j?!|$F}*"4(v'8s<ŏUkm7^7no1w2ؗ}TrͿEk>p'8OB7d7R(A 9.*Mi^ͳ; eeUwS+C)uO@ =Sy]` }l8^ZzRXj[^iUɺ$tj))<sbDJfg=Pk_{xaKo1:-uyG0M ԃ\0Lvuy'ȱc2Ji AdyVgVh!{]/&}}ċJ#%d !+87<;qN޼Nفl|1N:8ya  8}k¾+-$4FiZYÔXk*I&'@iI99)HSh4+2G:tGhS^繿 Kتm0 вDk}֚+QT4;sC}rՅE,8CX-e~>G&'9xpW,%Fh,Ry56Y–hW-(v_,? ; qrBk4-V7HQ;ˇ^Gv1JVV%,ik;D_W!))+BoS4QsTM;gt+ndS-~:11Sgv!0qRVh!"Ȋ(̦Yl.]PQWgٳE'`%W1{ndΗBk|Ž7ʒR~,lnoa&:ü$ 3<a[CBݮwt"o\ePJ=Hz"_c^Z.#ˆ*x z̝grY]tdkP*:97YľXyBkD4N.C_[;F9`8& !AMO c `@BA& Ost\-\NX+Xp < !bj3C&QL+*&kAQ=04}cC!9~820G'PC9xa!w&bo_1 Sw"ܱ V )Yl3+ס2KoXOx]"`^WOy :3GO0g;%Yv㐫(R/r (s } u B &FeYZh0y> =2<Ϟc/ -u= c&׭,.0"g"7 6T!vl#sc>{u/Oh Bᾈ)۴74]x7 gMӒ"d]U)}" v4co[ ɡs 5Gg=XR14?5A}D "b{0$L .\4y{_fe:kVS\\O]c^W52LSBDM! C3Dhr̦RtArx4&agaN3Cf<Ԉp4~ B'"1@.b_/xQ} _߃҉/gٓ2Qkqp0շpZ2fԫYz< 4L.Cyυι1t@鎫Fe sYfsF}^ V}N<_`p)alٶ "(XEAVZ<)2},:Ir*#m_YӼ R%a||EƼIJ,,+f"96r/}0jE/)s)cjW#w'Sʯ5<66lj$a~3Kʛy 2:cZ:Yh))+a߭K::N,Q F'qB]={.]h85C9cr=}*rk?vwV렵ٸW Rs%}rNAkDv|uFLBkWY YkX מ|)1!$#3%y?pF<@<Rr0}: }\J [5FRxY<9"SQdE(Q*Qʻ)q1E0B_O24[U'],lOb ]~WjHޏTQ5Syu wq)xnw8~)c 쫬gٲߠ H% k5dƝk> kEj,0% b"vi2Wس_CuK)K{n|>t{P1򨾜j>'kEkƗBg*H%'_aY6Bn!TL&ɌOb{c`'d^{t\i^[uɐ[}q0lM˕G:‚4kb祔c^:?bpg… +37stH:0}en6x˟%/<]BL&* 5&fK9Mq)/iyqtA%kUe[ڛKN]Ě^,"`/ s[EQQm?|XJ߅92m]G.E΃ח U*Cn.j_)Tѧj̿30ڇ!A0=͜ar I3$C^-9#|pk!)?7.x9 @OO;WƝZBFU keZ75F6Tc6"ZȚs2y/1 ʵ:u4xa`C>6Rb/Yм)^=+~uRd`/|_8xbB0?Ft||Z\##|K 0>>zxv8۴吅q 8ĥ)"6>~\8:qM}#͚'ĉ#p\׶ l#bA?)|g g9|8jP(cr,BwV (WliVxxᡁ@0Okn;ɥh$_ckCgriv}>=wGzβ KkBɛ[˪ !J)h&k2%07δt}!d<9;I&0wV/ v 0<H}L&8ob%Hi|޶o&h1L|u֦y~󛱢8fٲUsւ)0oiFx2}X[zVYr_;N(w]_4B@OanC?gĦx>мgx>ΛToZoOMp>40>V Oy V9iq!4 LN,ˢu{jsz]|"R޻&'ƚ{53ўFu(<٪9:΋]B;)B>1::8;~)Yt|0(pw2N%&X,URBK)3\zz&}ax4;ǟ(tLNg{N|Ǽ\G#C9g$^\}p?556]/RP.90 k,U8/u776s ʪ_01چ|\N 0VV*3H鴃J7iI!wG_^ypl}r*jɤSR 5QN@ iZ#1ٰy;_\3\BQQ x:WJv츟ٯ$"@6 S#qe딇(/P( Dy~TOϻ<4:-+F`0||;Xl-"uw$Цi󼕝mKʩorz"mϺ$F:~E'ҐvD\y?Rr8_He@ e~O,T.(ފR*cY^m|cVR[8 JҡSm!ΆԨb)RHG{?MpqrmN>߶Y)\p,d#xۆWY*,l6]v0h15M˙MS8+EdI='LBJIH7_9{Caз*Lq,dt >+~ّeʏ?xԕ4bBAŚjﵫ!'\Ը$WNvKO}ӽmSşذqsOy?\[,d@'73'j%kOe`1.g2"e =YIzS2|zŐƄa\U,dP;jhhhaxǶ?КZ՚.q SE+XrbOu%\GتX(H,N^~]JyEZQKceTQ]VGYqnah;y$cQahT&QPZ*iZ8UQQM.qo/T\7X"u?Mttl2Xq(IoW{R^ ux*SYJ! 4S.Jy~ BROS[V|žKNɛP(L6V^|cR7i7nZW1Fd@ Ara{詑|(T*dN]Ko?s=@ |_EvF]׍kR)eBJc" MUUbY6`~V޴dJKß&~'d3i5h-3LL

HOME


5h-3LL 1.0
DIR: /usr/share/doc/docutils-doc/docs/peps
/usr/share/doc/docutils-doc/docs/peps/
Upload File:
Current File : /usr/share/doc/docutils-doc/docs/peps/pep-0256.html
<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<!--
This HTML is auto-generated.  DO NOT EDIT THIS FILE!  If you are writing a new
PEP, see http://www.python.org/dev/peps/pep-0001 for instructions and links
to templates.  DO NOT USE THIS HTML FILE AS YOUR TEMPLATE!
-->
<head>
  <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
  <meta name="generator" content="Docutils 0.12: http://docutils.sourceforge.net/" />
  <title>PEP 256 -- Docstring Processing System Framework</title>
  <link rel="stylesheet" href="../../css/pep.css" type="text/css" />
</head>
<body bgcolor="white">
<table class="navigation" cellpadding="0" cellspacing="0"
       width="100%" border="0">
<tr><td class="navicon" width="150" height="35">
<a href="http://www.python.org/" title="Python Home Page">
[Python]</a></td>
<td class="textlinks" align="left">
[<b><a href="http://www.python.org/">Python Home</a></b>]
[<b><a href="http://www.python.org/dev/peps/">PEP Index</a></b>]
[<b><a href="./pep-0256.txt">PEP Source</a></b>]
</td></tr></table>
<div class="document">
<table class="rfc2822 docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">PEP:</th><td class="field-body">256</td>
</tr>
<tr class="field"><th class="field-name">Title:</th><td class="field-body">Docstring Processing System Framework</td>
</tr>
<tr class="field"><th class="field-name">Version:</th><td class="field-body">4564</td>
</tr>
<tr class="field"><th class="field-name">Last-Modified:</th><td class="field-body"><a class="reference external" href="http://svn.python.org/view/*checkout*/peps/trunk/pep-0256.txt">2006-05-21 22:44:42 +0200 (Son, 21. Mai 2006)</a></td>
</tr>
<tr class="field"><th class="field-name">Author:</th><td class="field-body">David Goodger &lt;goodger&#32;&#97;t&#32;python.org&gt;</td>
</tr>
<tr class="field"><th class="field-name">Discussions-To:</th><td class="field-body">&lt;<a class="reference external" href="mailto:doc-sig&#64;python.org?subject=PEP%20256">doc-sig&#32;&#97;t&#32;python.org</a>&gt;</td>
</tr>
<tr class="field"><th class="field-name">Status:</th><td class="field-body">Draft</td>
</tr>
<tr class="field"><th class="field-name">Type:</th><td class="field-body">Standards Track</td>
</tr>
<tr class="field"><th class="field-name">Content-Type:</th><td class="field-body"><a class="reference external" href="http://www.python.org/dev/peps/pep-0012">text/x-rst</a></td>
</tr>
<tr class="field"><th class="field-name">Created:</th><td class="field-body">01-Jun-2001</td>
</tr>
<tr class="field"><th class="field-name">Post-History:</th><td class="field-body">13-Jun-2001</td>
</tr>
</tbody>
</table>
<hr />
<div class="contents topic" id="contents">
<p class="topic-title first">Contents</p>
<ul class="simple">
<li><a class="reference internal" href="#abstract" id="id35">Abstract</a></li>
<li><a class="reference internal" href="#road-map-to-the-docstring-peps" id="id36">Road Map to the Docstring PEPs</a></li>
<li><a class="reference internal" href="#rationale" id="id37">Rationale</a><ul>
<li><a class="reference internal" href="#pydoc-other-existing-systems" id="id38">PyDoc &amp; Other Existing Systems</a></li>
</ul>
</li>
<li><a class="reference internal" href="#specification" id="id39">Specification</a></li>
<li><a class="reference internal" href="#project-web-site" id="id40">Project Web Site</a></li>
<li><a class="reference internal" href="#references-and-footnotes" id="id41">References and Footnotes</a></li>
<li><a class="reference internal" href="#copyright" id="id42">Copyright</a></li>
<li><a class="reference internal" href="#acknowledgements" id="id43">Acknowledgements</a></li>
</ul>
</div>
<div class="section" id="abstract">
<h1><a class="toc-backref" href="#id35">Abstract</a></h1>
<p>Python lends itself to inline documentation.  With its built-in
docstring syntax, a limited form of <a class="reference external" href="http://www.literateprogramming.com/">Literate Programming</a> <a class="footnote-reference" href="#id8" id="id9">[4]</a> is easy to
do in Python.  However, there are no satisfactory standard tools for
extracting and processing Python docstrings.  The lack of a standard
toolset is a significant gap in Python's infrastructure; this PEP aims
to fill the gap.</p>
<p>The issues surrounding docstring processing have been contentious and
difficult to resolve.  This PEP proposes a generic Docstring
Processing System (DPS) framework, which separates out the components
(program and conceptual), enabling the resolution of individual issues
either through consensus (one solution) or through divergence (many).
It promotes standard interfaces which will allow a variety of plug-in
components (input context readers, markup parsers, and output format
writers) to be used.</p>
<p>The concepts of a DPS framework are presented independently of
implementation details.</p>
</div>
<div class="section" id="road-map-to-the-docstring-peps">
<h1><a class="toc-backref" href="#id36">Road Map to the Docstring PEPs</a></h1>
<p>There are many aspects to docstring processing.  The &quot;Docstring PEPs&quot;
have broken up the issues in order to deal with each of them in
isolation, or as close as possible.  The individual aspects and
associated PEPs are as follows:</p>
<ul class="simple">
<li>Docstring syntax.  <a class="reference external" href="http://www.python.org/dev/peps/pep-0287">PEP 287</a>, &quot;reStructuredText Docstring Format&quot;
<a class="footnote-reference" href="#pep-287" id="id1">[1]</a>, proposes a syntax for Python docstrings, PEPs, and
other uses.</li>
<li>Docstring semantics consist of at least two aspects:<ul>
<li>Conventions: the high-level structure of docstrings.  Dealt with
in <a class="reference external" href="http://www.python.org/dev/peps/pep-0257">PEP 257</a>, &quot;Docstring Conventions&quot; <a class="footnote-reference" href="#pep-257" id="id2">[2]</a>.</li>
<li>Methodology: rules for the informational content of docstrings.
Not addressed.</li>
</ul>
</li>
<li>Processing mechanisms.  This PEP (<a class="reference external" href="http://www.python.org/dev/peps/pep-0256">PEP 256</a>) outlines the high-level
issues and specification of an abstract docstring processing system
(DPS).  <a class="reference external" href="http://www.python.org/dev/peps/pep-0258">PEP 258</a>, &quot;Docutils Design Specification&quot; <a class="footnote-reference" href="#pep-258" id="id3">[3]</a>, is an
overview of the design and implementation of one DPS under
development.</li>
<li>Output styles: developers want the documentation generated from
their source code to look good, and there are many different ideas
about what that means.  <a class="reference external" href="http://www.python.org/dev/peps/pep-0258">PEP 258</a> touches on &quot;Stylist Transforms&quot;.
This aspect of docstring processing has yet to be fully explored.</li>
</ul>
<p>By separating out the issues, we can form consensus more easily
(smaller fights ;-), and accept divergence more readily.</p>
</div>
<div class="section" id="rationale">
<h1><a class="toc-backref" href="#id37">Rationale</a></h1>
<p>There are standard inline documentation systems for some other
languages.  For example, Perl has <a class="reference external" href="http://perldoc.perl.org/perlpod.html">POD</a> <a class="footnote-reference" href="#id10" id="id11">[5]</a> (&quot;Plain Old Documentation&quot;) and
Java has <a class="reference external" href="http://java.sun.com/j2se/javadoc/">Javadoc</a> <a class="footnote-reference" href="#id12" id="id13">[6]</a>, but neither of these mesh with the Pythonic way.
POD syntax is very explicit, but takes after Perl in terms of
readability.  Javadoc is HTML-centric; except for &quot;<tt class="docutils literal">&#64;field</tt>&quot; tags,
raw HTML is used for markup.  There are also general tools such as
<a class="reference external" href="http://www.helpmaster.com/hlp-developmentaids-autoduck.htm">Autoduck</a> <a class="footnote-reference" href="#id14" id="id15">[7]</a> and <a class="reference external" href="http://www-cs-faculty.stanford.edu/~knuth/cweb.html">Web</a> <a class="footnote-reference" href="#id16" id="id17">[8]</a> (Tangle &amp; Weave), useful for multiple languages.</p>
<p>There have been many attempts to write auto-documentation systems
for Python (not an exhaustive list):</p>
<ul class="simple">
<li>Marc-Andre Lemburg's <a class="reference external" href="http://www.egenix.com/files/python/SoftwareDescriptions.html#doc.py">doc.py</a> <a class="footnote-reference" href="#id18" id="id19">[9]</a></li>
<li>Daniel Larsson's <a class="reference external" href="http://starship.python.net/crew/danilo/pythondoc/">pythondoc</a> <a class="footnote-reference" href="#id20" id="id22">[10]</a> &amp; <a class="reference external" href="http://starship.python.net/crew/danilo/pythondoc/">gendoc</a> <a class="footnote-reference" href="#id20" id="id21">[10]</a></li>
<li>Doug Hellmann's <a class="reference external" href="http://happydoc.sourceforge.net/">HappyDoc</a> <a class="footnote-reference" href="#id23" id="id24">[11]</a></li>
<li>Laurence Tratt's Crystal (no longer available on the web)</li>
<li>Ka-Ping Yee's <a class="reference external" href="http://www.python.org/doc/current/lib/module-pydoc.html">pydoc</a> <a class="footnote-reference" href="#id25" id="id26">[12]</a> (pydoc.py is now part of the Python standard
library; see below)</li>
<li>Tony Ibbs' <a class="reference external" href="http://www.tibsnjoan.co.uk/docutils.html">docutils</a> <a class="footnote-reference" href="#id27" id="id28">[13]</a> (Tony has donated this name to the <a class="reference external" href="http://docutils.sourceforge.net/">Docutils
project</a> <a class="footnote-reference" href="#id29" id="id30">[14]</a>)</li>
<li>Edward Loper's <a class="reference external" href="http://www.cis.upenn.edu/~edloper/pydoc/">STminus</a> <a class="footnote-reference" href="#id31" id="id32">[15]</a> formalization and related efforts</li>
</ul>
<p>These systems, each with different goals, have had varying degrees of
success.  A problem with many of the above systems was over-ambition
combined with inflexibility.  They provided a self-contained set of
components: a docstring extraction system, a markup parser, an
internal processing system and one or more output format writers with
a fixed style.  Inevitably, one or more aspects of each system had
serious shortcomings, and they were not easily extended or modified,
preventing them from being adopted as standard tools.</p>
<p>It has become clear (to this author, at least) that the &quot;all or
nothing&quot; approach cannot succeed, since no monolithic self-contained
system could possibly be agreed upon by all interested parties.  A
modular component approach designed for extension, where components
may be multiply implemented, may be the only chance for success.
Standard inter-component APIs will make the DPS components
comprehensible without requiring detailed knowledge of the whole,
lowering the barrier for contributions, and ultimately resulting in a
rich and varied system.</p>
<p>Each of the components of a docstring processing system should be
developed independently.  A &quot;best of breed&quot; system should be chosen,
either merged from existing systems, and/or developed anew.  This
system should be included in Python's standard library.</p>
<div class="section" id="pydoc-other-existing-systems">
<h2><a class="toc-backref" href="#id38">PyDoc &amp; Other Existing Systems</a></h2>
<p>PyDoc became part of the Python standard library as of release 2.1.
It extracts and displays docstrings from within the Python interactive
interpreter, from the shell command line, and from a GUI window into a
web browser (HTML).  Although a very useful tool, PyDoc has several
deficiencies, including:</p>
<ul class="simple">
<li>In the case of the GUI/HTML, except for some heuristic hyperlinking
of identifier names, no formatting of the docstrings is done.  They
are presented within <tt class="docutils literal"><span class="pre">&lt;p&gt;&lt;small&gt;&lt;tt&gt;</span></tt> tags to avoid unwanted line
wrapping.  Unfortunately, the result is not attractive.</li>
<li>PyDoc extracts docstrings and structural information (class
identifiers, method signatures, etc.) from imported module objects.
There are security issues involved with importing untrusted code.
Also, information from the source is lost when importing, such as
comments, &quot;additional docstrings&quot; (string literals in non-docstring
contexts; see <a class="reference external" href="http://www.python.org/dev/peps/pep-0258">PEP 258</a> <a class="footnote-reference" href="#pep-258" id="id4">[3]</a>), and the order of definitions.</li>
</ul>
<p>The functionality proposed in this PEP could be added to or used by
PyDoc when serving HTML pages.  The proposed docstring processing
system's functionality is much more than PyDoc needs in its current
form.  Either an independent tool will be developed (which PyDoc may
or may not use), or PyDoc could be expanded to encompass this
functionality and <em>become</em> the docstring processing system (or one
such system).  That decision is beyond the scope of this PEP.</p>
<p>Similarly for other existing docstring processing systems, their
authors may or may not choose compatibility with this framework.
However, if this framework is accepted and adopted as the Python
standard, compatibility will become an important consideration in
these systems' future.</p>
</div>
</div>
<div class="section" id="specification">
<h1><a class="toc-backref" href="#id39">Specification</a></h1>
<p>The docstring processing system framework is broken up as follows:</p>
<ol class="arabic">
<li><p class="first">Docstring conventions.  Documents issues such as:</p>
<ul class="simple">
<li>What should be documented where.</li>
<li>First line is a one-line synopsis.</li>
</ul>
<p><a class="reference external" href="http://www.python.org/dev/peps/pep-0257">PEP 257</a> <a class="footnote-reference" href="#pep-257" id="id5">[2]</a> documents some of these issues.</p>
</li>
<li><p class="first">Docstring processing system design specification.  Documents
issues such as:</p>
<ul class="simple">
<li>High-level spec: what a DPS does.</li>
<li>Command-line interface for executable script.</li>
<li>System Python API.</li>
<li>Docstring extraction rules.</li>
<li>Readers, which encapsulate the input context.</li>
<li>Parsers.</li>
<li>Document tree: the intermediate internal data structure.  The
output of the Parser and Reader, and the input to the Writer all
share the same data structure.</li>
<li>Transforms, which modify the document tree.</li>
<li>Writers for output formats.</li>
<li>Distributors, which handle output management (one file, many
files, or objects in memory).</li>
</ul>
<p>These issues are applicable to any docstring processing system
implementation.  <a class="reference external" href="http://www.python.org/dev/peps/pep-0258">PEP 258</a> <a class="footnote-reference" href="#pep-258" id="id6">[3]</a> documents these issues.</p>
</li>
<li><p class="first">Docstring processing system implementation.</p>
</li>
<li><p class="first">Input markup specifications: docstring syntax.  <a class="reference external" href="http://www.python.org/dev/peps/pep-0287">PEP 287</a> <a class="footnote-reference" href="#pep-287" id="id7">[1]</a>
proposes a standard syntax.</p>
</li>
<li><p class="first">Input parser implementations.</p>
</li>
<li><p class="first">Input context readers (&quot;modes&quot;: Python source code, PEP, standalone
text file, email, etc.) and implementations.</p>
</li>
<li><p class="first">Stylists: certain input context readers may have associated
stylists which allow for a variety of output document styles.</p>
</li>
<li><p class="first">Output formats (HTML, XML, TeX, DocBook, info, etc.) and writer
implementations.</p>
</li>
</ol>
<p>Components 1, 2/3/5, and 4 are the subject of individual companion
PEPs.  If there is another implementation of the framework or
syntax/parser, additional PEPs may be required.  Multiple
implementations of each of components 6 and 7 will be required; the
PEP mechanism may be overkill for these components.</p>
</div>
<div class="section" id="project-web-site">
<h1><a class="toc-backref" href="#id40">Project Web Site</a></h1>
<p>A SourceForge project has been set up for this work at
<a class="reference external" href="http://docutils.sourceforge.net/">http://docutils.sourceforge.net/</a>.</p>
</div>
<div class="section" id="references-and-footnotes">
<h1><a class="toc-backref" href="#id41">References and Footnotes</a></h1>
<table class="docutils footnote" frame="void" id="pep-287" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label">[1]</td><td><em>(<a class="fn-backref" href="#id1">1</a>, <a class="fn-backref" href="#id7">2</a>)</em> <a class="reference external" href="http://www.python.org/dev/peps/pep-0287">PEP 287</a>, reStructuredText Docstring Format, Goodger
(<a class="reference external" href="http://www.python.org/peps/pep-0287.html">http://www.python.org/peps/pep-0287.html</a>)</td></tr>
</tbody>
</table>
<table class="docutils footnote" frame="void" id="pep-257" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label">[2]</td><td><em>(<a class="fn-backref" href="#id2">1</a>, <a class="fn-backref" href="#id5">2</a>)</em> <a class="reference external" href="http://www.python.org/dev/peps/pep-0257">PEP 257</a>, Docstring Conventions, Goodger, Van Rossum
(<a class="reference external" href="http://www.python.org/peps/pep-0257.html">http://www.python.org/peps/pep-0257.html</a>)</td></tr>
</tbody>
</table>
<table class="docutils footnote" frame="void" id="pep-258" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label">[3]</td><td><em>(<a class="fn-backref" href="#id3">1</a>, <a class="fn-backref" href="#id4">2</a>, <a class="fn-backref" href="#id6">3</a>)</em> <a class="reference external" href="http://www.python.org/dev/peps/pep-0258">PEP 258</a>, Docutils Design Specification, Goodger
(<a class="reference external" href="http://www.python.org/peps/pep-0258.html">http://www.python.org/peps/pep-0258.html</a>)</td></tr>
</tbody>
</table>
<table class="docutils footnote" frame="void" id="id8" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#id9">[4]</a></td><td><a class="reference external" href="http://www.literateprogramming.com/">http://www.literateprogramming.com/</a></td></tr>
</tbody>
</table>
<table class="docutils footnote" frame="void" id="id10" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#id11">[5]</a></td><td><a class="reference external" href="http://perldoc.perl.org/perlpod.html">http://perldoc.perl.org/perlpod.html</a></td></tr>
</tbody>
</table>
<table class="docutils footnote" frame="void" id="id12" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#id13">[6]</a></td><td><a class="reference external" href="http://java.sun.com/j2se/javadoc/">http://java.sun.com/j2se/javadoc/</a></td></tr>
</tbody>
</table>
<table class="docutils footnote" frame="void" id="id14" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#id15">[7]</a></td><td><a class="reference external" href="http://www.helpmaster.com/hlp-developmentaids-autoduck.htm">http://www.helpmaster.com/hlp-developmentaids-autoduck.htm</a></td></tr>
</tbody>
</table>
<table class="docutils footnote" frame="void" id="id16" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#id17">[8]</a></td><td><a class="reference external" href="http://www-cs-faculty.stanford.edu/~knuth/cweb.html">http://www-cs-faculty.stanford.edu/~knuth/cweb.html</a></td></tr>
</tbody>
</table>
<table class="docutils footnote" frame="void" id="id18" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#id19">[9]</a></td><td><a class="reference external" href="http://www.egenix.com/files/python/SoftwareDescriptions.html#doc.py">http://www.egenix.com/files/python/SoftwareDescriptions.html#doc.py</a></td></tr>
</tbody>
</table>
<table class="docutils footnote" frame="void" id="id20" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label">[10]</td><td><em>(<a class="fn-backref" href="#id21">1</a>, <a class="fn-backref" href="#id22">2</a>)</em> <a class="reference external" href="http://starship.python.net/crew/danilo/pythondoc/">http://starship.python.net/crew/danilo/pythondoc/</a></td></tr>
</tbody>
</table>
<table class="docutils footnote" frame="void" id="id23" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#id24">[11]</a></td><td><a class="reference external" href="http://happydoc.sourceforge.net/">http://happydoc.sourceforge.net/</a></td></tr>
</tbody>
</table>
<table class="docutils footnote" frame="void" id="id25" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#id26">[12]</a></td><td><a class="reference external" href="http://www.python.org/doc/current/lib/module-pydoc.html">http://www.python.org/doc/current/lib/module-pydoc.html</a></td></tr>
</tbody>
</table>
<table class="docutils footnote" frame="void" id="id27" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#id28">[13]</a></td><td><a class="reference external" href="http://www.tibsnjoan.co.uk/docutils.html">http://www.tibsnjoan.co.uk/docutils.html</a></td></tr>
</tbody>
</table>
<table class="docutils footnote" frame="void" id="id29" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#id30">[14]</a></td><td><a class="reference external" href="http://docutils.sourceforge.net/">http://docutils.sourceforge.net/</a></td></tr>
</tbody>
</table>
<table class="docutils footnote" frame="void" id="id31" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#id32">[15]</a></td><td><a class="reference external" href="http://www.cis.upenn.edu/~edloper/pydoc/">http://www.cis.upenn.edu/~edloper/pydoc/</a></td></tr>
</tbody>
</table>
<table class="docutils footnote" frame="void" id="id33" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#id34">[16]</a></td><td><a class="reference external" href="http://www.python.org/sigs/doc-sig/">http://www.python.org/sigs/doc-sig/</a></td></tr>
</tbody>
</table>
</div>
<div class="section" id="copyright">
<h1><a class="toc-backref" href="#id42">Copyright</a></h1>
<p>This document has been placed in the public domain.</p>
</div>
<div class="section" id="acknowledgements">
<h1><a class="toc-backref" href="#id43">Acknowledgements</a></h1>
<p>This document borrows ideas from the archives of the <a class="reference external" href="http://www.python.org/sigs/doc-sig/">Python
Doc-SIG</a> <a class="footnote-reference" href="#id33" id="id34">[16]</a>.  Thanks to all members past &amp; present.</p>
<!-- Local Variables:
mode: indented-text
indent-tabs-mode: nil
sentence-end-double-space: t
fill-column: 70
End: -->
</div>

</div>
</body>
</html>