From ccfd92e558528aaebcdc63fc700b8119e76c9b52 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Sun, 9 Mar 2008 21:32:24 +0000 Subject: [PATCH] First pass at Sphinx documentation. Most of it still needs to be written :) --- doc/.static/sphinx.png | Bin 0 -> 34025 bytes doc/.templates/index.html | 60 +++ doc/.templates/indexsidebar.html | 9 + doc/.templates/layout.html | 12 + doc/builders.rst | 9 + doc/concepts.rst | 14 + doc/conf.py | 125 +++++ doc/config.rst | 204 ++++++++ doc/contents.rst | 27 + doc/ext.py | 4 + doc/extensions.rst | 110 ++++ doc/glossary.rst | 22 + doc/intro.rst | 11 + doc/markup.rst | 835 +++++++++++++++++++++++++++++++ doc/rest.rst | 251 ++++++++++ doc/templating.rst | 4 + 16 files changed, 1697 insertions(+) create mode 100644 doc/.static/sphinx.png create mode 100644 doc/.templates/index.html create mode 100644 doc/.templates/indexsidebar.html create mode 100644 doc/.templates/layout.html create mode 100644 doc/builders.rst create mode 100644 doc/concepts.rst create mode 100644 doc/conf.py create mode 100644 doc/config.rst create mode 100644 doc/contents.rst create mode 100644 doc/ext.py create mode 100644 doc/extensions.rst create mode 100644 doc/glossary.rst create mode 100644 doc/intro.rst create mode 100644 doc/markup.rst create mode 100644 doc/rest.rst create mode 100644 doc/templating.rst diff --git a/doc/.static/sphinx.png b/doc/.static/sphinx.png new file mode 100644 index 0000000000000000000000000000000000000000..c91dc4ed4c34658b08d47d38dce87fa1fab20c01 GIT binary patch literal 34025 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 HEVyZTCOOOOjUQx6h+_}-?6vpf!rrc% zVaZn{nBHk6E0>$`q|oq>cTqt3u8=6>6526Nqf`oBGPL5y4kotI;5{^S+=@}TsG4nm zrPBJ7A<1+_iR%#zDHKovSW*eg(eXz=VW5b@_uR z%QURTk=AfQtsj@ChKnWa{(mr!l~1*OcMud{_dP4>e9Ath?iVbWGkE?b0oTrMK;6JE z6}rEI?-lXn7h(HBJHH;ev1-)3Yf}l;xaGMLzv`!CqPHk=SM@z)oF0zv_CM{qI{fY$ z?ew@h5?6x14sRtb?#d>}yt2o^42ko57&i2v^~KV)d&(q}ri~q_`c4d~ z3{Rzhz@tZwRjOh1ht@LEiY!iK(^<#KLh1IrKpcVF0a07@pJPc)@wQxO2R>WSil|Wv z?elN9={MOj94-VaF7yAu{p z4%6Dyw0aS62u*l<3mgX|-P}y_0UZw5M-##)`(hZV$7;Y?Qg!_8+|GnT-Q|1W5hCH! zoMi#@9M1awx6<@~ARsoJY|`tAQb=!>EX=^EU1^MxyViu}DbKdqr%m_1er-o!l@^Fb z%TSUh55=WXX8s&{Lx}5sQOuA?aWDLNL{*(J9c#Yl%;<62A#!Nws&yiQq~M`6uW?&;)QFA`%S0`_p{li8R?YpL=yRsXbPdjjh zpEm9O%~6AoX+{qntwHgGO_%yFQ5ZHhHZG#Xq7mchIt=)3?YN61D%;33 zV1I$J^9)9OeQR(NKN9-vgAv&EmWzpx3UrJHc#}w=!M!f3)EorS5-;7Zcd2nDVjh=0 zBHwpT0+senM>U;y1p6}SbRbAHH+Q(n%-AtWO2sVNScD+K>xdi1r_CU6vR z9adLt`MAzOm;07lWbpHmZ6HQ&^zUZVuCmp18y_kOO_|cqWLn~H6hsa3GlgT$io)Xb zx)Ds%DNNJ^>CzMDgT0z1btLchS39zr!x&Ro65~HJ&9WYjRFSs7Y`tM{$uXdov(G23 zJYUal;~`3v)x|Sp$1!K*f_7U8e)Ef&S8^22X^lpB{;I()I4y^|;VAaz z)K4JIC$WL+?F)~~C!IAli*j=DWm3RmEZt4zSj1<4*kV_AG!e&@?>6rWb3UIv*vsoHkXAuRf9l8acW+Nj}sQ}AmeHd^?jq;_tb{xhY^ zoine~u=s?!7TvIR z`h*0d9v(aQn#^+JnSwuvgRkcpC_Th|aq~eJ_2)vDmYtVv_jsk?+ulP50DgqzYV004 ze?GUOSv>P-RU(U0D0SMP{=LPJXawvkywBl>*>))m+zXVRc`&qD5cz%pR6qQvGb)ab zT5$>M=K{B^DQeqN8rYpn>)tq z{gV^~NMmb#AtfQ9118p&MvTA`c*s)c2P4E0zpdqi+5fuFPf@zGNaD4_kp*9A&+@ua z5pG3D7M2J8Eh?(z9@ce|?0P{Er!kV(3}RQ#VCag}PR)ePl0Nq%?Hin)uohIW$A$lN ziw1s_c94=r0%z$17o*Om*5`b0?2+Nxh$plVGs+)=D_UR) zw3dmTIh+T&`$=MOmjpC=1oUG9IP3bsn;%~xxf(u;%u*G@uKi=Sf0kIuaxRLKFSXGE z5~=LHGEv?9TI#_nx7y)}-(hWpxt33Hzw)}%{Bt-W#1w3HJtq+$jqybbHsaT3uFmXn z|8|F2Lk*huuAK`C9oX#$fB6Q!p-t$zVylOtQqXE!gTG5p$`9<2>!#jYuv>{2>y|h) z+uk|0de#@u6&1T@fN0{`2^3dZ4wkeA)5i2(UCp4FQk_8l+>j$3V2p`zV zp}EPhv&zOMkTMUSTCCp4B9c+2J!Bmp87Wfkg;G+ai~c%4MSGla)T8Fdj9=hM0{^A< zmXZ@c7II3IKGA7AsKgtck29@{GM!P>B+W|r^BV+okzrTxR>Xz9C^SvB^^i=aw@^*p z`{J|3-zW=#rva^K^+eloh{|$iv-9{+JhPIBYWtfQHQ%NCGR#voU-u3Lpl+J8&%d23 zD%Y^?z+QX3jZ(ii|Kp^w10xMISKsM?!N+a?N(sr8)YoW9T7bb-o)^%y!9U;exqypJ9TP^w~(KMO)j47D=9|{gIW=T zuGcXE@)?scQ?<>xpx36okIcWs&K#FoXA?#@CK4XxBl(<+8DV@3XpSQpn=}5M0b#ic zWWpdyr^GIi+I`w6Q{dUv(UVAT)CPC7x7b6qsDG!2A$#{s>ug7v!?60(=+q};`$E!S z_IEED+895vw?@jl8tlILb6W?AFyQb|lFC<}=$g6Z78h`U#Cf*pM+82=)`fc zSD6!7CW>6*6!p_oF$yX{A31?P2si2Mk%1Uc9y0OubW!kdr480@-L`IZ<^IvTdNkNK zOUrL!62y8V=5>4SfD}W>q%tS5Jwgub)b^dwKt~^ce$I6}k4UF@PU6kyk?C(L5Q&zwq1$M=N8>ERmdC$eg_pF!5Rgs6 z2i6c!b$yO>e2AFYx)JDWqUTDzga$>0|Gwy8W0x8E)h{EAs9Js~x9HO>YT71rc>nP? zOIU)_T_nq|g;Uh5_f&9?h961&|3LQFVG?5c%_$BA&KDqgd1)zUt)w*+!Qy5H=}{TV zgvW3amFH(dXZ+UeXDd)Ap`mFervCnZ!Zk&}mj=Da_Q|H3Yve#K(9st zZ6C!P6=a+mN~>JRAqOQ4KMn)6&e9jUT%MZCmjeg4N1B{3U8CKy3iU(rz4EqA- zUFAyxk$aYT3ijC9-vcoWrcd5LyclKT-Nj{S(;+)2pb zwGR*W{-0k2#EAHOMnE)H{l4`JH9NugHD3#6?JNmFZi3ibss$idWi$6l{8WatcxC^%efAl6f5`G**EP`C z91|(ck5Mb+;Ud1fDfAyxpEnY^ASc}1j(J_z{Rh%9MDG@G~}Ro6I1Lfsq4*%46Plyd|d)FgTQ0tgsyJE zFZh|}+jEUe74m;tqsCQ_8nCx^2;9vLO>Y?8{xJHkq~%NoHD4#A0!xnmds;Oa>(vUpt_ zausFMi?DzTKe!NXq{Hg3%hkS@1YKzOu{Js80G?rtiPA+R?*DlKI0$q3cf$t0+7Z)z zj>Y$WLvO>L>|tJhQPga8NK!EPW)s8+2%jc!(xNx zBz@x(MXXZZWbiDcIja?#VXe6oM#HR|^o4yFfzV9FG>s+!%I!GthR#%8!%zfXY_{H2f!4GT z_0D~`_piZ$Kd>m-<2IHYII1GXl;D1#Tki1jF}}(a^2;!p@%c>CL+xT|6Q5WBAC(gldNyj`My2b z7aXJ}7C9*soVv&|oYLp07SuaV#!d+Ry%{iV<3&3VI1jbTnb6nGgz;#S0}2&SRaEkf z6;^Fpy}D=hGxTkSs(~QLB9r7KnqMb}v{kh9LdfVyFuBth?ns6A7PzKzG&vgK>rf>K zyUYF4^o{M{{ht}Lkjw^5SO)Yta6v@I7`I&gbZg!$q zq!#w?jEyrLdE!>vlSEz}B?g3a3`l-X7rLO`u-NvGO%o3?!5uX$^f(urGYnqjcSFRp z0(9Mn2#7P#U%rlELq&1rst?P(U_!+0sN0-z<_*w}*wP-XykO@axv` zQdsbSL6qkmOOMGF3Hfw$c6G~$HM*r|SAhcGmWG*aw;7?(cA&0Zoh%g`;KBddmZD*d zILyCN(S&EN?z1Aq0}lrOoPglm8PmntKfVKz%sI`&s#diJJU&B z=gF{8C1Vm$S$GoV-6mz;XnHjMZMKO7u`LYC?bavzq&UNbzxmle%k4YPY3yZ8;;*(iDb!_9e%j+YbGCy z82NjCHXmQ;RDND-EHy9Qe#Gb<@BDjFDMrc8$9!PN~;iTB}K4 zw(GL42Lain4P7+HB5eJphuuIsF}!1bt*IM$e4lDCzw>zedCoB7;;Nez)Y?tH@{gpk z5sXjl)zG0-6f1oAiDwIE*mKndNdLL^m`1ksuAw!86OZY*hIUTc*-8J|8zc@!4vyVV z%?DI8zfpF1818!ItiCLz)tj1_bRsZ$(#V2-mI8uFRu(wX!(2Xfe{J_%%rn6}D>H7i zX1-CaBU*E-P*XM9Wo&*ztZ^5DN!uC|PeYI}D{ZGbLt|qp$4!TNSt&v>5HOz{7?`kK zAdP<^GhXn$d~LG}Gh4pqvu3JO4U#7_u}wgU!&J!wIkQ!P9cSep2WdSyj$)r_1Qr1! z??Nsw?$?X=KVXAI6%$P$w#HiT^}zIv-0@|>qQ$2Xst1Ou9NZc8LLR|BpQ}A z@i*d{iF$cT{~!y;a)P0}vsSOWE7f!%x6{<1;qpIVm9tI=9nAZsY(?$smys@QRf#jFkAhz# zkKU!2QU2<}6$%8$A96WX(=A+>sWck}#)OeP1}qcGX6}0KQnTGfIM~})zZbcWiXN=I zzM#PvyFrv8&1TT*pZF@&d*oqt}6&tB#NK z@l9THcu-c13Xz86vk}Z`U9q@<mR zaw51^jy3^bXeFd1VsQ5uXeXbCXb_NN6P)UUNU=&>4PPs(8Xj`?s`b2A6(s;ivzjY- zDH^(k91APP`NN1xl~zCcOL4BbT3D?8M8+(ZM3Pq8c4xPIjZ>R%S}RsnrQ(>k9vV78 zmRMiGAs6cCq4$m8bFLu#L7n!2z^%!0PaIJ&F&AAmxW_dij5CdW>4cB zKal9MacWSV=3^Pr{M5lkD@P6INZ(~rObiX(HLXX}q@q7f>F3pU1N~?UUhMnBkg^v( z$Z4wLLPk8RC~M=OR?&=IpZv}ZbIHs6$_eccQ7lGf9dYK{5w{POhn@}Yfk&F*|Ee4v zL8HT+!N&c~?L1VY?hGGUng|FHl*kT`?^D$v??C?5A)YTO=sL_PLK4dw{d|?Zx^wm4 z?YN}Rfs0r^j!b;Fp6g<;k(h|Eo@Fkf*^gL)ez>tsLeGkf}VTw8LwO> z_VQ_vA~~^UkZC3S2h3R!2pbUdO@2O=Nz;xWHd+yQLCD&y=*au+gh?e+0DJBH@!^ho zy{QnlzhIC;xDa-1|L+J^@kKYhxC8a3An-HDX|@ zM;z293H3sLx#Kp!D~uSvM2uW7ipcBHF;W6zy#v$s#HdxFgWek_ZQPIsTYI)e&^@{D zk>q&U+38$(Z(s-VF(a_r+UYQkc3iJPbEI>1&Ewl(W7@p)&s5a!L`tki#Gp^9|53aJ zSN(5o1)#|hWBX(VR-Tb(;SB?GCqoN`2a9L}!$X6V8abah*wddY-cMR^6WN;3ZV^^A z;*E&q)?|{Zs;C$`Jb}Ygv3Gx)C@{EK{EZJd_}#_h;om6@B}0ETXc_;FA3wBoJM-KV zNWavy{7C4kmP@zQ*HPMXaHXW8r2ng!1z|dd0j>gif8)UgUPA$c&xkEFo>syKHR)oY z1e4&!Li;UGcG&Yfir)l2Q6#>mKz+41kp8Tus%-Aa?QP8Vwt5?Fs01E8 zi0%@p_(4C1c427PDQ9VoQ?u%DB-68**9|75Ei#dkk`h)Pk`4II&+BySdP($72s=95 zfIhvhE92mD9}Q&trRMA&$GQEe(()1-2xGsQZz}AnY&rKW6pFHTy3hD!Mnxf1@UVYJ z5Y>@?_=6FyDEoV1l2y1sE6+?>^D>s^)JEn-S?s!#TAc3zY1I>NpM=~l|5k8!{`*CQ z_neJCX-o4=n8`MffazAZ`U z!i=4elDp4ye!H=4drdhyF8muKBV)N@jQii|SK#z#6k=cYwl88HRX+VPq8GJII^p8P z(%z9K+vTPp)KeA00L&RJEp6nOAWRbv1x@#lgBD-E8V#GQHXTVAqOR;YnQfL$H@L`n zq>#~6D$vDcCV8t6Kr{I4;xp7y%*zsa8)wi)P24P@tVJUzMhe6tT3G%r z(1_UxckR!%Xg#ooJ9XAXV7CEkY)~&NgH153jC?s(7|Pmt78-utdS@!=#QkIfR4i^L z8)B`gB68WM5uN|<>v4^|{&|FA-+{4LE@tni+=0ACig@kU|D|GXc(}b$hb=}>3kBCt zQ6_6XAzFgTTLGFnl}cJ>!tdSfg(D-6Cj0du+VA)HN4HP<#|{>A%5K+ zp|I_N&(V*UOIldcbor5EBG-e~&8K`W>%}QunWP;|$!@1LFOOW~M@SAYbrqXvbbl@1 zLm@i{qwqa9l&Ld=#@XP5h?BF04~S~dHbhr8)q#?xHt@;&oc4P9TG zDO5o)IlI65>F(K8 zO!4!9F*Lt9KvB>n6->fJ!MAD?ap*3KoavV#MI5oP@q_pZBrWK;y=(Y0_}JPC&#kI+ zo;VCq`Od;E>|7!GOHvi-_MK(DFRajs+|C&m#TEloYCJDJ$>SqNe!S&ABe6;Cs?`L6+@)+?zjsEpaeA-1wbn z(=VEVO(KDKGx7e&$>*u6&m(mx2-9xA45)~nr=Gq2#3u7x$tbt=D%af3KHWZ1a6TQk zsIFB`8df9l%`jfhdN+=V(!km{7P!_xbTCZV%z8gmQHG6(tet#jYW;}q)P}9(zF561 zsFH!tC;4&tO?NYMhew3c?T$#NeH|2Llk!V50;6tF)Shls`<@EMj$%Xetb9%TsZt$Nf%UA$)ZXhTp7G{qJ(!=Vc`;KbIkT0~>aoux>oebe=Lue193G+(&r-ihCOcY6?*7-5~X1{O&8@g<~UXsBiORxI@iKH6-umlR3X zj4vJ4Z4I%UaZ^*X{)t~-x?WG=wjis_4QVI&$7)v4PGl6w3t4pW8wCU62%_^bAJM`% z16q0*yXe5eI)7jK1|bBg9~#!=KpSVaE%GsyYkgCOUs=QxyQoRcYj|G6Urh*{GINn< ziI7=4 z3jAw_)fZJ$tC;=ZNA33R`nR5?(=A){%{P^FB~#Mqeku2-SCb-ts+vVPCY0^GEj!;Y zhvQ(hL#msYLfMlc(Zd279${k71*u_6o70d|LT{4@$ab^s3B;pQ)ZPl#-_KzI(Q{)6Ec;TV8r`84+P`?+<3W60W|Dj@NcDVh?v z8)lh54*@s7NB(_~@~eh*W5(bF-kD?{Lt#!cF&_@yCB%$=FKN7wT%1`&iH?eDYLnL4 z7n9(3kpfAjvJrJap`% zzWu=h7WlH}8_Mm~sZjIkmEIVFybnp_3@K`D3#6$r@-QYJDfLCpw9P0VzfqYJgAfoP zGh%HgXzNKb^g~uaXQPbmM!MKFL(ClSs3{EWsGI(A4YYrf?v+teQE>)2YIWQXvR`21 zh;Js{DSmX~qn155m^?G0ZDCney7|s^H!tZA3HmB`Cm0hm<2hRIb0xwN8hBpzQx0rt z4t@pRLwg;GqX-E_*7En}`{7HY7VXb6NLgdvdIQr!_@7TA6iy#7A>dO|&wpTwV z6b0Xp6v0-RErwYbS!I;+BolmTr)YxShaAXaQL*cjex(xqY=e=;i?8WTv{`` z0rA51Zzuz1Zq&;=M6ELh*|-XEbZY%Z^0zb$St*gi#D=9s5BU0#&mb0lp=2rI)9VFH9w9T zp*H4qXSi`Yne(2<+>V=T=iwath@+0mpBBsp9!%km&F$gtl-?5qNRK)lciCZi3qux_ z5x%7JJAT!UR1GegAunU##rjYtNmna1QHTpu;_^WcCYM5q;H9VeR&tPrY0w+pg`Pf) zl1w`)_Z&%hGTDfIS;ELppwlFScznPFQbwQu#4Yu+tm~=%r82Lt2m~(Hur{g0ZuH=v zqt_~)*}*{KhO9XvGXI)aO28c4Q)-Kmva&+=rrgQ+Th|6hreEufPD0%-8Yzqbl2Hr zq9-=3{GZzw=9i&zMP2Vg@}88HBs9o4^5SOY*Am}NRLiQzP?NZh8yGL8Cgmkcy2&b0 zYVpXwHH?uph^FV_HoW(LqZM|7jEWT`#m*utq|3Tu?|m(VmYPky8)%7oc!e3 zz}Xuhw#Dm1;=cuy+0|hMD1r@nP zjnDd3C_-Bm@iQ`}w@oR0splkk0JtP@gjg0)@K8$J)5c)@Kva^Q~&?s~B{Idts>bJhMI=9tSTZ@%4_G%hrhUVg667LZy%NX?BE+|;a99|lC zD)++ch%1oZ6vInNidm|r?x5a+EJ4B*2}q`=37sm|1}JQ5I7P>C(>-vyO!&eje1TZf zz~ZBjs^$_V0pIgh?B0WzEmbjMc9qq_y_&w|84A>|2MTrdDaLc>#Hc-w*!HQ8QJ1p( z$wiIptJYR$&aa7yp1k9|_EC;;=3eRTHNhki5~h2;)?VQ|Uf{k1VKg{7e_|=#afR@) zP2950;n(==c~AZ$E!(x>&E8^biC^ByZ@l->%<|kCROMleevlLqzrm^Fx{6=Y@ydd| zR{CR}^;6QC)>kc9W3$szd2(2fmR1CBu(nChH%g|WD(z9#0$B)&h_trCNQOLaGN%3w9`#?Z| zP|011h-rgtSvWY%Z#BG1Y|5;m`IPZp(;H4e#5-p1Ev16LSj5LMoKB}X$yQwKw0?y3h>5fX~M@bLA# z@dS+_hX@4))f+>}t5)E>&^UY+q&As$82ue6Kyc6Hs|vT}>g^@Oj?0y*ghXrw!?nx< z*|$VBrRZ)*p3Rv!#_B^_7#RB6&`6fm*Zy%oc8>@Y}5h+^SAN@r8)e{-EVW;pRnq<(BKJ2i3Qzxo>^7;j26U9k36jh-=OnJvT9|T5%(!-db9SEHFVaN_)2}3 zcwi%w>(nYwo6STv=4OM*86~BE2)8H8!_D`6N$!~y8qSEe)`gMa*;j^cj?wZdI;8SN zbF@GMSp%h4>!sAoUE=R~Vz^)}1$j};mtLaz@J6VAD{CIk%iR`*+vk6Dk!LLO*#+Ml zkxc&im}e0leX;B%fMM~`p&AV5fBE$RdSVasYhB;J+A+7hkPr!xLn+Bgrp8c35l4TU zN`<73FPNM*2K)brdaJm$!e)CoL5sJzQ{26{TXAV{cPPanxD=vG#SakYxqS@*{=sCCR^=89lYVjyNf%^>f^|%R(;mjrb#?H?g<1acl^fP97nYx2_ zOvg5Sb-U$C=gOtn$3$n2R>uwh6Z}CCr%;I>ftp%0b#_vIGF&p-^cX*~x^KG&5`6N( zetIn_ZSioUb&!Oz56OE^rE7s-*USgmOgfx&Ck%k%XHc%QViNJG?3X!SNXAeAIx2d% zzL}ts0v05Vd`A-D6VgO|@RLS2pV0)YfpoXwXLy+}ImQ+XfS!(*{tX4z_qMyAsG*#? zYM$SLJ3RJUnO|{yJrx+zaPY279B^#5ql6gOG@KQNEb;2PJmjTFJ$^P=gCw=};2O zzo4APn3$}&d~$r3GX96w9IrP-r8yV7pLs~f$~X>8oVmMwgMzq!%u)UEOP1@pZWd5& zVl3vfeS!Nm7CLG5=&~r|>v6%(#2fn7aKz*&$-g6F<)$}djE^!048y^IZl3Vh4^6^8 z7gGG}O}JN55=;pDdD&BWK#-RIGzOaURR(JrGEP>KBcc;^Knf3L&apu@9N8`I?XNZD zE!aaw$5hT!7z6oZ_P%LRnmN*4`gJXD{MWtE%hD0sPIeLM_35*}`WiRZJ$w=3o1ee*sRQM-t>37FsnT}$dno-4N7oNlMHzc9{&}%&zf0ljy8E3InHNbAPM-YmG zKo#m(Fx*xe4a>0A*iNK=_hr{Jm`GolgY<0A{!4oFgS)Se?gvJNWdy>jVlsAxaYjkX zkMMdDnBE|@PTo7kpfndwQO=K+R-3AYP88>*bPIB^7Myk7axN7EB@v3^Y=BmoBTFQY z)S7q8j(O>(RWt0Qv62oKgNSukE~cyB}UlW`a|!=R)bupGl$Cp z3At-Y81LiHu2u6ju@C+J)>Et}VYQ1(gAwMGFO|`}0&Rn`cbq10CI+0Ct2y5yqoK>Y ztDKv0pY|%Bbta-dS<9HN-I`U26c5E#UMlc@6uI}Gx{M;5DIjB=VD?NzSyZlE`lp1^ zB`0s0w!)WeF=xiG$;>HHpuSt3{sn>1mG0JU3FnDEfvnBa<@9{9#474DJZ?{RPs#ppS#m7ChMfpvy zl0^*QrHD37-*xI1IU#&Vnz0=o zeagY7SZ;@9lkA40c*b{D%Sv!Ng?@kjZlrB{gOYndGN!T9UkWxcwopO11fUE@(GXV< za|?A{z+xGl{;fnj!7&k`$AhabWVU?%_qJeW9L3gAZiMbZ(7VBLpf8+i&FwV>%vC*N zf439#@&H5)_a2^c0yYa?sSuF(04JZw%1EE?TXIF{r+$n2$&8Gx0z#eeArq;|SuidJ1^@x_fKqe+0zM)t z>^xwtUoQTd-UDic6hCX>kWMPgmRq^o*I2l(0zc}sX)Iy9rvvjW(Z9ZXMTI*=@lr58 zUxPa(x@W;W@i&YsHN*I@bKdy?TZRO~=%l$YQ=NbpM!=#(S_!KxdM_W0{?e?Qi^#e4 za{^(f&oxM6DTdX~#z$X@&Dh|KO)pEcyJJJI{xy_v-7V09l#0%SRln&7%ZuF4z-zEz z$S+PwAXUxK&~O@U(FbNeD$8#EE1SjasXB)jZ=-Me9xfA;FWTK@T{NfnG{tHhsGf!B z_Qh(ME}`0uOHOx&*sV=HrB486OIcZD^|i>zev2UaHdUJxd6hgV1z-)X{lwX^onGgC zb$567wy6q>Fo2JSm!2XZmimnY?AsCiZv$RNK_A#_59mhTx(%+3+<{9kFC^rn*tW?i zyht|x184M;LcDow6Myo?LgVI_&R(_z+r)-fG`F$)RM^0N5s&`tmG3S`oxp=K@qw(= zz?7n$%H=ndH<(@d!LL(--VVS=!1Kk&utwxw?W59JL4Hi}|JYE*O0k^ae-JkP@tanp zZo3_k`kKRdOO;3!rCHAuqlHn5?JCFqXMNl_9{cwX&M=~qbRO3KARTr!2nVF~#y055NHtOXCI6c~ZSqTj8rsHcH;8_#Skk43^(fwSV-u%62Q0&cI zXW`Bz0qjUlaE+GjfpRWD!Qn!JUSr@|!gAt2ZpHQghJIM^&ydnol^OSf+AyPgE9_m(^|PeL3aV zR@e7i@5tV_uY$CP<5GgiQ9n(!@(7*)5_1a15gr21i5R7W)4^8^O0Pp?6s>t)#gStU zb8S#Frj@V1BfQ#o_=1=;=Q-l~;@HPh@T=_4een=)4`OKwXwj~_0B6c}DuR%|{P>Mc z3*pUS1p8`C3;*xsdrc_i2WL|%bo++QD)=7|zdty$v!U322qDvqW@hgmLEOof5YQlY zD=AC>Dah->wU7?z*^%3{>NqXT%x>JqD}8#Yud!V`H7ryIn{{YK!o zmUy$>Ym=d~LyqR86R9w@=-5$FK1r1_?163?=e+wd>=?Nd;!0bH0dYk$X`eyFg*QJ} zm}n@R6c($qT5oq-?Pza*rv4JZtq-C-bgBOz(7=ADv2*cB$XA!VQr8;~uY?!wzlp7^ z(X>^8llU2mlc)I!=DP3+59a)E0HcI0CCnvUXG_JSKXGx`CuCOJD`Tu3SZ{>gbyE1E zJ&YJU%~zSdDvxrQR+jQvWI@syDkWRl$Dn$Jh-c|h;*}c{8otY)U4DMlf2P{L{b9n7 zT1q?LAIvfG{h&Q|N4TTJNJ}Y_hBA(ntdY7C396>mBJ@Hm>Twn3Zr=RS@E>OQ&*^JW zVZt8HYs+n6duz1QziBc0ZC1b{%Q3~@%MT{SLe3WwWR@d)Eb`@0kq@$?BO;1^Nceol z!&0x|Ivn9{YB!DA(dr5YU)QF$Y97ZKP2ea_rzk73Sr~j`q!k$o2}l&>KTuOsQ$Y1# z>Mz2wZ9J%X9oe7|nt)DQaA{7DtNLN!kkZ3qH)-j~ujzCXZ!01~g1G`UQ~*mj^(?L% zweql&>H6jjZVXJAz>U`VpWq0KkHXAFW`7=IPF1AF?=)C0Ks9y0zZe`w%0#n3S01Md zw&2H*3GlrbaC-@pFMEj=^EhGk3(*d#0mG1vL9z=9`f0blneVe#)pfODM=GtJKK1g# z4ZHay8B|?G7|zrgDMzfJ$k;3z1rXWhwajt8%f&nU6wfCLZb~O!?y;WE&D_YO(~p=f zpW_|%JZ56pV`doS$4U?z`=d4+zQ-W8ka$IcFOP4p!A(Era@I zO%mY};!thjsxP1XL)rB^=r`}?59jBT9S7F_*E6?>=5C#gUX5R`~|vCvd$Ick$2w_9RX zci-7q$Vd9NT{7B?$KGgn0RGf8jN4M2*lnRk%5_K$q>a@5FnO(KMCqaE@A6!Vco-C)&BdRVTf+H{)_;VOMj`tfrX#1yeUYQXpdB zkGi^g$AQR(;b~Y-IC_I38GFD3w4;2_rPe&-eXTvn4LUIYs89QFlO2}^s|ITP4Re19%+57b(BITG*FS;&muW*LIE28)~ z8OIiAj;e6v0FLGsKZ3BA32RN9efZrGE?wr7lSM?7KHhYaa7N&%e9HX%wL!Fv4)dGf zo6x(^M9{xAj53iAv({6)ub32O`6hg_*>)v=?)-L&{}(nKp8N7LMQ)>lM*|xrR54Xs z_&*11OMIvR$>6GVu<72gy=eEF{Gv@Oipma!4y6w{)kT`EN`Ws2TfT0v#!5COKuJL} z1kci-eWw_7>lWD(Iv7Dp-ceBMh68zGS<&Y~{2afXMVBd1V41WXNp zkBo>sSpnkmdnuP(Vr^)%Z$BqgZ&xO+=%G(3Vm215{|9)r1lVFma_XHb+rCycf5z$7 z+LUWUx>l2H{rGOP(9z0~lZPg?jkII>xAX6!2D0!DRupkV5`j$TIt&b>y#mP~gZ2-5c*wiEBT#zi`mF7b zkpBaEgCrBeZ$*)u+N$(gb3iWwfdXTk)Wz45G;`m#7cQY&u@}FN_I_jcR=aCO0d3t6 zh-|IZAOvv*ZP>mgU3Y`zk`T@8^!G*=?)1cdQ^#G$i!}sZSW%Jo%$q;WSlPE`J|hj; zGZd%SQt34zGd?Os_*%7$VAfbF$RXP5U1RISA}T~fD2}Vq&JFU~ z9?Uq?UJ`jy9u&R)lq_xC9xFQh)gWM^+^HhL-GN194hQaW{0Zg<;XFpq-0!7A5ZCFE zt=9wawv(%C!>LqfN(*aObPHQJh5ZGgc_Q|7$`nsvP$G6TC!2^ESGRQq>H3pjF4=kp z83_~l?t2xpY(DWvL3HIb9}tXQ2=AKG;Lt%{6O+&@+1m|0;=^_^>#-r?|JH2(2}@Z; z{VgQD1idh7u&(}rAsLfk5E>AeU!QjgD)_k-MM_RK~YdT81M`tDcxA{q{?EK8(%nJ_~N|NiD9R4%*?T^($`0`$RmCvJ6PK6p&!Ry;JNb zU*)EH%JXEHTZEOxkzj1}m8^Y852-j%ynq{VZg={Blg4E_yhu(IT17xh8CNC3jsfEl zC&!S&Lsu-zY0dRsbv0X?nT(B3f!d)1Q*_N$$q>a2aq8`=x>WE;9P8E2>0K<;_wco> ztnA=Zflix)RMNo`fv)?rlu_q06E7H@2{BDVckE74f=FAzz@t^W@#jk%R%F=>)b&Vo z<TW}*)H9IK^V;L#|TzII;ik7Gc-EEZ{mxzO-vG#=%{uCJd0Pdb9 z;2mtcPdl10yc!%NM`has;E!xF{~jIwe@?J2oS74rq*u{njpJ(Cn{3#o^$J_CQu@m67IG!y78f z0fA5*v)L$GnqGeM9{?rJK2kuWe4K>Nhh6%i2e~^H_J+6PwffKP?d|xxuhLKDgu-d^ z%nC=R+0^I6jN*)p8FWPTxHeuv2Xx>45k?L^23$$LZA#_o0#pD_bOC(8R-E29coX6m zqW=ddVUnUkT;pB%_TW|UNDK(pR#ehC>&dy&+`}O%%DEcR-qG$0m@D8fhCpHa-`20O zP4_0&*Hn^Ec$G^1sAWR1zUQ2 zz7-73`SwS#@~teMqYSm2tHGA0^nu6$sweQ`>grU#rL)&{-4u><@i zdf2I{E>r;Q!1Lc=>@;vm?H?A~|FyW35>xg`K6rJ(rC7>N_}^M(Z@QV}fR6hi;iwL- z_?c7d-y0HM7B|a7|D;iSAMuSyU0KDs9H3!CF79muX$j)oO;`!FKmK&jF z{Z3oo?{`7ibajsdNOUKz8BpE_EifD)I7nmm4#+T6#uo;9pA@{d@;1LSGh-y+oQ`H~ zjmnfG&6j|RXj0A{3hN&c${C;s$^j^loIVA30OU%NY5`!tSHKn=;X6M^;^d0DSt&Rk!CR2^NAYiZI~00gNQDISqyEhDHB?07^&3OEH6W(J$*b0fAa z_(D8M0H34|(&UKmJgrfSb-Py)J_1cpdzb7A%#LWN0Qhqvm~JKe&963zV*ROzChPI=Ms3yrMaU^ZHtcfV<-dKdM(T$zrtu96I*TM>PB&jI;KA zI!~ZM`+T1l{Z=>|qJ@IM_nb|WhU`W%gM+t|4rP0b!Phz#c{M7G7u+6K+S7qLK(i8T)ML|mj z?So7^1c<_L+(I24S!S?T)hO|S9n$+!feXoc2_ZvTOdqw8udt)?KKx2zJ)IGS_ehr%hK zHs;mpKj!MV{a!WZ?#$rasrpcE@!#`h5*bG>5SP&qJyS_Mkh8>hx*-bZ^dgXcvG)0J z(fjsP2y}`3S*qvBvdEk(XW#&6pprFB3rGYk09!G8=>RwYQTVM2ys34-7AC+Jc!G4U z41m(gP|K3UROY{vkt>UWjY$Ml96Caak6YmGaRT_@3CmoJt%3KL0XN`@Hb8D>C~hZ8 zuPq>3k|YByAGtSgR^DJeqko5I|Kca$mAuy+uz_T<$#V5d1rURSAZ&>M`~`*&QUT{u znP^eT#~;~;5INAdBEZ-^Kqpxq#F8MYS8RYI@;Mx!!Umok>D)vx!WOv3mBmGnIo$&E z#0yCJD(VN20+1s(nF~f3yO+FoFnd4+yeV6l3I!}KdRmdu=#v4e73iHUGlFU{VdH{! zMHnvxM>HGSr65KT}3gZ^H9|3vBI`j^vTuXqm8jT++OHWr`Kbdw3S`E6}mV@ zfQLl5rUO-mNG9&GHn7zLpU9g!U~x9nKzh2KuaSP0LQ=!o3e$X;TYg70 z{$gkmk&s9JgjYZI4-bH<>sO`ZQ4bCzl3omeD9NJ_dhc8O-{C%`zgQ5V`wN(90Zxl{ zMfBIA-edu9SiPJ8(KMB9G`#2!QGhkMEB%jcmC`IM#OAoYfOS{Z5D+s;DZ&m*6RH@s^5RAP*;$YHwG#= zn|f7M=)HU$596_2;GZ5QfrTY}TRu`ZU$e=&w82>KzEa4nbJ^m2Uy2i9D?Dv+g?y-y zUbJgpa=on1KtchTAq>L)+z;nfspsiC*MbXZX`sQ>x~gUJHwChKgJR{Z5T zA3$qH@q04Mf}&i8FJb^s<56tl;CIG=#e`XS09FF+2&S%5#or4EQfuSFexAy<5}*bC zo|sYi4(?uT#Yu&3@AMXo?MNSGLMyB^HX;D%PE%0{Pu7%TU;pl!q3Oal4Qtsm0~v`& zLg5<&yW)rZr~{5?<+J(6k-CHAHlcFM$MEOORDdX;9o_a7>&ifd9_(>v^8QtYGy@FM zJUP>}h_^lf|Ihe$fc0w+p`vt+-yZ|~6T>}2d+u;3oe!ao`A_M}2{x32TdV*TYO_IR z(oB>O1+GVehLFD@UQ`VP+V>mOH1stkZFX6fa;s9uN+F`(F=DFT>nWZVG&PDgrq<&v zfC%Z~?o~l+q}~fDPITbv6vR_EQu@JD8Stb^;wWb(1#&N8AZ%e5qmfRPs^7^+Fv26AFMlD^m#AtqrD4L2BF3lNmW%MsEU`fUhmPupzD}gx zpVIM(00%|-i%6y&%-kKcBfnLt-R^{4d%w`ToPb+F*ovAx3xS$2D!w5}wg^*3W1JI4Z# zEgl+bBqUdQywHJvS-5Hl$ii9MGA?qG(!~KUtK=+fMGyX^g%FdVH`tyx$BF?IG;#0G_;yv5n_l2moj{-GWOv zB!`1}32P3ptCjz^7a+{-Qm_9 zV;b>EqF=GbWD0n2Zt*wd^6X14I&pdznC@IYRL%7sFJ`Ei8HVm$LUN1Hjykh|zCUo4 z5)hQHcmV-X%`qRv#+;{VDD67Lk0rz=RZcTHvvoJB7Oedt*!K zA!FoI3C5JFaMDrK{4Nh;G$InFDhe5d((Ok|tZlYO1Gsy}(Yvgp94D`@FQL;!uO~t| zjGcKKG6a%7oQ2n-ZLP6Kz8I&heL`; z6i!bS-pvhyYaC0j{DbARa01={wQUCbOlxm7N3WX_2lrT1pBw>Bp#X4&;OHi-->A)h$Qu5 zOpf*6&i;&dUGd&2s`^?%^=!36n_Pmc{NG1BDvO-SS+sdo`U_~0bai3cZH)~z>UPju z1aAU`xOV&_S^!9w#VNhFOnpXr&-z3J0iuA9u&AQ0*{_LO zu=CsH@VnNAzP~YzbYjX{doK-@ql$p&qNIDzlv-}S zqOVh4%Ak?CC;2cM@ZlfT-_yUiLt$yb8^+ci7^|n+i79XBZ-@mcZd?y_&cIVeWekVB z5U|%{P9Crb!LnR+%sB(dK_Y>jC&o0;0cwEgN`|EN z;j_=2{ImMkE?y}Do(JxPCyp?twVpy(-&AxJYrws@V8r(ddX_)ETL4v=vg5y-Of9X- z9+6t2$(NMHXs2bhy`i)uda9hT;d z^%w6T$?akq&^?n8bfQ$CW{Q(wnZ?MYv&B?E4*KBVR)LDzD>VA3N#(++vG-U8*{_SJ z%uN}|pn~=RKGfYM(6$$-?0I&FsA*ZA408bh2FBV(aS};*Gr0QTddnqW!v5BgE4$&y?ViO@`4i z+Yy}iuie_T_y(Gu{(qexHE}(4dEd}ir0(G!pT28;g!cJ83t0*OqTlJAUD`8WRSA(2 zKVbKJB+^S#{E;jm?c#4FZ$p>y253Zf{Fd63Q+56Vih)D-(lbt6*p8bWEe%yjF{al3 zogczc_Dia}^xMdm+E>G>{=f&~J^t`$95L#)6RcC_@$pSnP3-*NE{x;d>gbbyX(5y@ z0hlev)f@+iR2>rJ<4E4x$<*4Xuk!e>X|El)9F%HES87X@w8t)M?qTW18oR}iJtg>J zeMZK}{717QM3vqAZssH|9#ok^y;ljGM&9I;7l@;8;`X77~6+Fyq_k z^wdZ7l}hrPe|orw6xEHup4MTin7&b}=>F8rZxLd*VxIbM8|y-tC{lURjhF}6wiGF; z>ae2z*CoD}8libM8Uw|IYYKt=#_amK$TzvcYdVTR%!p-ig&Q6`-eHO)nFNUrH=)s$ zdlZnUn0{Z7j-o&Xff1P&xt4NZU~{XnLgWE17|x|B<_4uc3~^yEZK2hQ0L*npxc(Ln z^!=s4;!_;+wR^X}s<87pqtXvZW7E>(*;zp?*pY-#1vUIo^@u0Y@ljMED$w%lqK-K7BG!@(~by?vE~1!c?}-2 zmh$P{(4h=*Vsk0nuTMSHb3|qIxic?`y*>Ix`i*Nc+#rjd@!JA4UT!}mugNi`H# zgT4rNp@B{eVT*dYH`7;uaU5{op_j4<-(CVPDz?$FHj3$gfzG~vn2hQLHO)AFHg37M?nY|{C4{CDI%OGG_eI97vX9~^8oiWhAn{` z>QJ369xsPOk=uE=uDo?7i`s>&C18#|-mZZm!WQ$1Aoc9wEP9UKHB6B+>6uc4`lyi=RFi4}z;;|i=|1#hye){Yxb#QO5*t5vNbJ-Mz zSK&akwCW+Zb85!Si)y<(ghb*pgKJ)+Vb9F=g=%&;P#4=}Esod6BwM01*t00!mW&LL zoIG(Cl0y=EWneWzaom%#H~a>7B+^vjWBoTC=O>Tt_SrzLHr|SMi=5Cu<~<)Z1uoO& z%=es#dx}C0^noXb=kvLzvSt`ZP8;LeKjaudOf+Effl^?RZT1f4p~Zp6%#b&JBid`Z zfKJjsN<7o-WR>mG22xjp!_Ga_iLm!azlMcwqz~_8c=kC*Qd(1S|9mfKd*%utP5E*& z&PxsbnD^H%b-+HoYyfXi>1dF5LSts^r)0Db5z@$PD^L*nk+ixEmwQih_`r+eRaj1j zCp0izZcy}aE%AGi@=GBYdy|E_qf|=Ytw-@{Pm^*Z1p?R_17m;J{v7{Go|4oA%Ufu@ z$=~93|8*SEgaOy&jeb6i$xk*(k6rJ53Og5UN94xfoK~c-E9B$4+~gsdwxKMKFmmGN26P*ZE=h+R+0!74 zp}ZWqAJ!H%LCAx6a?0Sx`=*jks^LqRA7lPpOnGsECkl0=!N~C(hwuO1K{{^By~q9$ z6Kc@lB}8<=SEkEf?cdHdjH@^ok^RwnJrcH}E#9m3U42Ysu$oToZ_YUx*@jhhn+(OI z$7g5$L(EdF`Yq07E%(3Bx)xGOIrhjVTXnYi8krIInUC;rcgSh^)J20X`vgK=IoE}% zlk?su!HashQk%6NFQjL6E#JNT-PqW$F0R-7{{4Hm&0K^}3XU-x(h%-JJCLHwDH$|z z$3ov=jdzKoiivruDcjol8q4b{lUfuG6kf|H|Mmryh2LK=q9T9CBrd3V%2?Sb+B#BW zfCJ~78b$&HNhj86FvojLHujI{G8)Ulp;AG*$~H6PkKzWFQW_JPDt)Qpp&j|12n8*d zYzSo#dH(ba>N7VtC-$O| z&XlP;KhpH2>3``2K>HhGsW*=T)(R<}q0@wHrIMu9#N@1~h(kZ*l?Jyr(miRdhpx=Q zYq&$MNg=5RPM^_uClp2}YYAl1mm_lAOcEANLSQ&J{=x=sjT|9Rgz|ZK8xod zBLb%oap7G00OBjobX7mb3t3B7)Jk{h!;Mi|&c`if2OW<#A9jOuXY{AK=RqbIW{X{% zUMB+dg#~VIqs*Oim#B&#RB?Sb$Gv+I=Fn6)+3Y4s<;cQ86ZPh5v!z^BqRe}x9L-R6 zU#F)R7HpsV5$fMQ9ppY*Dc32?+SO!nyj7b03Et0%kCskI>jKgoi&6L8-}4O9m%Ky9 zzUolk%UGlKWKPS&xH?s3n{&lC;L)(-MkBAh(Pn)vqufF#@-71p zblC68PxRPDog=Mo{V!npUjk){3i4b~aVfZ*x8lG?pW z|8RsmXNZxS3e<>Ba=VEOtmh zkT1+D9xiSuHqLV($)powEwso(lyi{z{E6|EBIK6MH%@Mzy1-gQ8*0ia-AdHBSiItM zgzMdW3Lq~C`}U_ZgwK?2O?F}V6YH-vI^df4pZacvkeeNVFjakD*JHzkE2dz}*-(JS z{D?JLQe;msrU2RoQ5@X8KEPv9hk`wbjkc3yWt@b3@yqoaLx5tLSHAv%?=NCozI%Ph z$y|ji#i7I=+bz&Y6)8G^@HBjChkFu=jv1=~5Qn)pbUSQ=V(8@=tuu9xEOg)-Vlgh^ z&X`9jOnNSAWVRI0>V9DeEZJkXba23-SoQh5S`sUCa-znLvk;#{!Mx|%_I!TsG^zZb z?yW+PwG<5Y`&EY4KV#Wn*EZfX!qv`J*M{8pD+RoM%|jkhZDh^;8%Hlvm;yKhq6o9J zx{KZWxW#eaeSU0%_Ic0}S}S-9J;+TvQsca=%F2f2GQ`}9$+EoKA>O&zck46sM!w^q z%TE?lW=l@ImHrM-0o`P3BNURfOrD$(Y*kC0T~00x?QU_oPADFw9N(KskC3Pi!6@L| z;EXCH(IOm%m37>@TWn!dGWS6628yg-u{u_!vH1|Huk}|cieV*`5q@21#|r0Mne?)y zdNkxzby7NJqoB%)($M7FwvUzRb%L8Uf8=D)kr%e!M8S!Eu*reHPori}#Kc#3Qlm|# zs-eHk*NTZFO+{R|q{ocW+vRsrAZ-F^p}W$o1A2vOIUeHr*)2Oqrle2#tiSC6Y;yE< zt=yV_j_c!XJypLdyT5NMw>;6MXy4B};8?_gT@uPDywE~61}=F77M~bk*E+5+HA7QI z*BCX2W#io`<0EHzIQgS%JhPVNx@dqER9I0eKIN%)r|;*E4b(tRGO^Y%Dn1b2MIY z+8>O{dfSJO;MYO) z@C2b%c^blK^>-99{|gpNWj+%+hi9#cPnPgtuX)+SJ32s3PI0>mk5U**P{XJ>wJu)i zxA;h>^hq*G+8aEG{4p>1a1OJ*)J1pKbO!=g-BS7iFY?3NN2^3%J_-5XzZ4Bk zh9VbaIcgGBx2pyIjp`tB|fuPW1x>0Q&Kn2F#* zS7HjJ9ITpr;_Wq};K2*_8VFr6D4!h8_~cF@nA*~E0_{Oh2v&wDPnV|{_z5-2^pN!O zSd#oh$Ql3XQBOwd%dp^Ksk(Wa#W<_~vbkEVkqj;G-nFbrEsluYB=`+hcarZw$`Z7M1FR@+vd&`QF}v*{GtU4 zM+ua86c%l5qUG&uNZ6w%kGb3Uu5ULjr5(3<-?WKw>RDOyRv?s{R2Mj&%4)7umSWUs zDTy*{F1dv3Fa%&g8U^z14zIp`wEz<%uljzOFW6lG$?X^N3%IuOedz-+7F0wDD^ZXk zt~-0nWMD7A8SYt7>q0;c0~epat;rHFuExy`QIuK8=|5;l4VrBe`9&7y>?kK8+7aerd?vE%7CX~F_d5|cq5I>r z1w2e-v%FeCC##?UJG@E8@QhmNCW%NJk?RNW2%zTNlhH^Rqi%7}H+7N*Dz*PQU3V^z zm-@126I?F7DGB!_9E@IuGp0kh6$~?G}J@>hZd*M zqNJryQKf^u`J&9fckLH3KN&j>;wAJir6ohV))XthA`+lV2rvwtexxN1D2%6h%u9sG z1Id%kw$_FkYko(-xi`4*@*OVUS+W5osPvcrF<}DR$rKlIhr;yqL`X!Y#7)lN5luIOVYLe_ z_^KVvM%|OWeE1y6JW5mDgaPPD0xmtxlcGoBBJB*91MtTvBp}^A!GXRlNYLx}cY+Lr zH3uH3tlF__0x?tWtpp=T4h;z4?im=LwBhbInR0@-VcCVsl^2Wdv;Vss7H^V9K64^4 zZ8~>;MNCRKn}|}@^Kn5^X$?#&;XXX4iQ>IMJAA^z8NI6L^nq8Exrh1z{8b}&u^&-9 zl-TJ9J2Bx%5S_dP9~zPDL<1btMwLD$VWdY)R@2bmy|25+Yt*Lv7#kXFpqN!qHQ)0& zrkf@i?OF)5h7Cb!#+r6n_m)GmqkNWYX)vR^ zu!|`;Jzdb1a)pZcUpeKTvl0371-#yad>#Z758%nj558-xF2T#Y9`mm>+B0HIk z{xNazs`6kLS)85~?BtJ!>LzZJ9p;j!bfRtcDWx5i7X>jPY{0(fqHx$vwW&mZ5jKU( z1=*M{h8UHS@eJj`bQpbazE4s<6=&I&HNTE*3VcgcKNRqXZKy65C&?vDw9JXt60OWV zb-%AG8<&%Hefqe!_(CxG=8=yke8N#)-{)J|i)^xuwMp!-Aka(dqMYTkR^z%7+ZKlow?QJduq485{PJ+8$iUIYrfcpa zF65~daWjv^H7-47&36n{cX#4G2SK^gDI+m48BXQeX)!yfpkCQ;ozq!k7=+hsFCwG= zydWDBHxN@rqUN)@EgqU>Kszrr?7l)SOdHoAQ7ANVi+6B2I+Ht^~#<&8Kgd1iukjryF2?wacQ z2PW$^4*94evEc3zUPQg)588uxHS$@6QQIcV0RRL6d1(oa5+sLSrKI*{Ca2RNwose7 zsPD~*#g4Rl;su{m;-_$PVa~`4(we4`@g!Xlx_BS(DyTppifE`iQnMopAd9^=1NFBb z2yAW!I{eex7}T11wkY34(Z~$017qjWA0H@=D3F2={N9NZFh1X8+iD9&U?s_%fvFfV zt+1Ub5INLhvg3z$%psG6#sIQR{BTTWl%YB09QO)Ss55ZumOVy;G>oB>P7Ush{L{kns8x)yB81h?+hGn!?wbRHtl zH-A(^vwMxN>?S0mfBiukJ_T2S{SSD+&-o%QDbb0M-P$&}?DRnp<6%M=gKsG8x>rWB zyz+s=-Lz!7Wtp!z9)XR>*eScA!uZfIOduTie$jtLh*WspTnDA&sLO2bsd@I1H1L*1 z`iS`HUwV=Q@hT^z*j^iAAcjcx*j^J0s%;5h*pj9-mk^AY4*d~|HE*ap*_;3B*_Kk; z{i!76Hk_bWA{qO%OjXOX_a@E60cQbG}%@wnyc^q zynHshL!Vqr1E9Uk@T`Q^#0ckk8AD^Me4>B+UsE_KZxI||p~iR`i5@Mr;c+0TQfH@v zcBgb8G9zt&WkK01!Ae!G2dE(VnV7#9_a^G&{sb=n&V(y%(%FxCDwI7RTDs!#Vv-N) z)S|6UenJa7CthE*i#SBLQWZR`>FA*zAq>2HLo;)8t~zeXXNR3zzJKbkQEN;uLa>`d zt_^)GS}4fYZjZaG;$HiHl>Xmjz!lK7+_Br|&H=Gkq@4Cu&AGO?!+n|@+Kigs33rmFi6&2;x%cD8drQ|$*}eYAT+i@LhC4I1 z9=&rXBXh&=!i!hT^n^c7T-o_CCojps+|KSD<1KY-v!V*$J&!GX_}=Nc%#32TzV_BF z`k3Lq`b)qqCUV7}`z0@$z?S`6=y(%Yh%~8?p-}2Xoig3y_dW445yzK?LX2PzbS>YWx{ds#b*}> z-IzC3K0Cqo`~TFe75^vR>)g0V&=+>dM`_;0G`>mFEyVG`_ z^qre`@9w>SrUw>Yjf$ddrHh{)5jQWq|8(bF{`Bsni}KTsz&3~=(+@fh{pV+^i246c Sd{YAh5O})!xvXWelcome + +

+ Sphinx is a tool that makes it easy to create intelligent and beautiful + documentation for Python projects, written by Georg Brandl. It was + originally created to translate the + new Python documentation, but has now been cleaned up in the hope that + it will be useful to many other projects. (Of course, this site is also + created from reStructuredText sources using Sphinx!) +

+

+ Although it is still under constant development, the following features are + already present, work fine and can be seen “in action” in the + Python docs: +

+
    +
  • Output formats: HTML (including Windows HTML Help) and LaTeX, for + printable PDF versions
    • +
  • Extensive cross-references: semantic markup and automatic links + for functions, classes, glossary terms and similar pieces of information
    • +
  • Hierarchical structure: easy definition of a document tree, with + automatic links to siblings, parents and children
    • +
  • Automatic indices: general index as well as a module index
    • +
  • Code handling: automatic highlighting using the Pygments highlighter
    • +
+

+ Sphinx uses reStructuredText + as its markup language, and many of its strengths come from the power and + straightforwardness of reStructuredText and its parsing and translating + suite, the Docutils. +

+ +

Documentation

+ + +
+

Contents
+ for a complete overview

+

Search page
+ search the documentation

+ 		+

General Index
+ all functions, classes, terms

+

Module Index
+ quick access to all documented modules

+
+ +

Get Sphinx

+

+ Sphinx is available as an easy-installable + package on the Python Package + Index. +

+ +{% endblock %} \ No newline at end of file diff --git a/doc/.templates/indexsidebar.html b/doc/.templates/indexsidebar.html new file mode 100644 index 000000000..5fcddad6d --- /dev/null +++ b/doc/.templates/indexsidebar.html @@ -0,0 +1,9 @@ +

Download

+ +

Get Sphinx from the Python Package +Index.

+ +

Questions? Suggestions?

+ +

Send them to <georg at python org>, or come to the +#python-docs channel on FreeNode.

\ No newline at end of file diff --git a/doc/.templates/layout.html b/doc/.templates/layout.html new file mode 100644 index 000000000..c8b9020ef --- /dev/null +++ b/doc/.templates/layout.html @@ -0,0 +1,12 @@ +{% extends "!layout.html" %} + +{% block rootrellink %} +
  • Sphinx home | 
    • +
  • Documentation »
    • +{% endblock %} + +{% block beforerelbar %} +
    + +
    +{% endblock %} diff --git a/doc/builders.rst b/doc/builders.rst new file mode 100644 index 000000000..ee28a1b4b --- /dev/null +++ b/doc/builders.rst @@ -0,0 +1,9 @@ +.. _builders: + +Builders and the environment +============================ + +.. module:: sphinx.builder + :synopsis: Available built-in builder classes. + + diff --git a/doc/concepts.rst b/doc/concepts.rst new file mode 100644 index 000000000..7e10b3032 --- /dev/null +++ b/doc/concepts.rst @@ -0,0 +1,14 @@ +.. _concepts: + +Sphinx concepts +=============== + + +The TOC tree +------------ + + +Document names +-------------- + + diff --git a/doc/conf.py b/doc/conf.py new file mode 100644 index 000000000..5ccd12738 --- /dev/null +++ b/doc/conf.py @@ -0,0 +1,125 @@ +# -*- coding: utf-8 -*- +# +# Sphinx documentation build configuration file, created by +# sphinx-quickstart.py on Sat Mar 8 21:47:50 2008. +# +# This file is execfile()d with the current directory set to its containing dir. +# +# The contents of this file are pickled, so don't put values in the namespace +# that aren't pickleable (module imports are okay, they're removed automatically). +# +# All configuration values have a default value; values that are commented out +# serve to show the default value. + +import sys + +# If your extensions are in another directory, add it here. +sys.path.append('.') + +# General configuration +# --------------------- + +# Add any Sphinx extension module names here, as strings. They can be extensions +# coming with Sphinx (named 'sphinx.addons.*') or your custom ones. +extensions = ['ext'] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['.templates'] + +# The suffix of source filenames. +source_suffix = '.rst' + +# The master toctree document. +master_doc = 'contents' + +# General substitutions. +project = 'Sphinx' +copyright = '2008, Georg Brandl' + +# The default replacements for |version| and |release|, also used in various +# other places throughout the built documents. +# +# The short X.Y version. +version = '0.1' +# The full version, including alpha/beta/rc tags. +release = '0.1' + +# There are two options for replacing |today|: either, you set today to some +# non-false value, then it is used: +#today = '' +# Else, today_fmt is used as the format for a strftime call. +today_fmt = '%B %d, %Y' + +# List of documents that shouldn't be included in the build. +#unused_docs = [] + +# If true, '()' will be appended to :func: etc. cross-reference text. +#add_function_parentheses = True + +# If true, the current module name will be prepended to all description +# unit titles (such as .. function::). +#add_module_names = True + +show_authors = True + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'friendly' + + +# Options for HTML output +# ----------------------- + +# The style sheet to use for HTML and HTML Help pages. A file of that name +# must exist either in Sphinx' static/ path, or in one of the custom paths +# given in html_static_path. +html_style = 'sphinxdoc.css' + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['.static'] + +# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, +# using the given strftime format. +html_last_updated_fmt = '%b %d, %Y' + +# If true, SmartyPants will be used to convert quotes and dashes to +# typographically correct entities. +#html_use_smartypants = True + +# Content template for the index page. +html_index = 'index.html' + +# Custom sidebar templates, maps page names to templates. +html_sidebars = {'index': 'indexsidebar.html'} + +# Additional templates that should be rendered to pages, maps page names to +# templates. +#html_additional_pages = {} + +# If true, the reST sources are included in the HTML build as _sources/. +#html_copy_source = True + +# Output file base name for HTML help builder. +htmlhelp_basename = 'Sphinxdoc' + + +# Options for LaTeX output +# ------------------------ + +# The paper size ('letter' or 'a4'). +#latex_paper_size = 'letter' + +# The font size ('10pt', '11pt' or '12pt'). +#latex_font_size = '10pt' + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, author, document class [howto/manual]). +latex_documents = [('contents', 'sphinx.tex', 'Sphinx Documentation', + 'Georg Brandl', 'manual')] + +# Additional stuff for the LaTeX preamble. +#latex_preamble = '' + +# Documents to append as an appendix to all manuals. +#latex_appendices = [] diff --git a/doc/config.rst b/doc/config.rst new file mode 100644 index 000000000..0832fbf96 --- /dev/null +++ b/doc/config.rst @@ -0,0 +1,204 @@ +.. highlightlang:: python + +The build configuration file +============================ + +.. module:: conf + :synopsis: Build configuration file. + +The :term:`documentation root` must contain a file named :file:`conf.py`. This +file (containing Python code) is called the "build configuration file" and +contains all configuration needed to customize Sphinx input and output behavior. + +The configuration file if executed as Python code at build time (using +:func:`execfile`, and with the current directory set to the documentation root), +and therefore can execute arbitrarily complex code. Sphinx then reads simple +names from the file's namespace as its configuration. + +Two conventions are important to keep in mind here: Relative paths are always +used relative to the documentation root, and document names must always be given +without file name extension. + +The contents of the namespace are pickled (so that Sphinx can find out when +configuration changes), so it may not contain unpickleable values -- delete them +from the namespace with ``del`` if appropriate. Modules are removed +automatically, so you don't need to ``del`` your imports after use. + +The configuration values can be separated in several groups. If not otherwise +documented, values must be strings, and their default is the empty string. + + +General configuration +--------------------- + +.. confval:: extensions + + A list of strings that are module names of Sphinx extensions. These can be + extensions coming with Sphinx (named ``sphinx.addons.*``) or custom ones. + + Note that you can extend :data:`sys.path` within the conf file if your + extensions live in another directory. + +.. confval:: templates_path + + A list of paths that contain extra templates (or templates that overwrite + builtin templates). + +.. confval:: source_suffix + + The file name extension of source files. Only files with this suffix will be + read as sources. Default is ``.rst``. + +.. confval:: master_doc + + The document name of the "master" document, that is, the document that + contains the root :dir:`toctree` directive. Default is ``'contents'``. + +.. confval:: project + + The documented project's name. + +.. confval:: copyright + + A copyright statement in the style ``'2008, Author Name'``. + +.. confval:: version + + The major project version, used as the replacement for ``|version|``. For + example, for the Python documentation, this may be something like ``2.6``. + +.. confval:: release + + The full project version, used as the replacement for ``|release|`` and + e.g. in the HTML templates. For example, for the Python documentation, this + may be something like ``2.6.0rc1``. + + If you don't need the separation provided between :confval:`version` and + :confval:`release`, just set them both to the same value. + +.. confval:: today + today_fmt + + These values determine how to format the current date, used as the + replacement for ``|today|``. + + * If you set :confval:`today` to a non-empty value, it is used. + * Otherwise, the current time is formatted using :func:`time.strftime` and + the format given in :confval:`today_fmt`. + + The default is no :confval:`today` and a :confval:`today_fmt` of ``'%B %d, + %Y'``. + +.. confval:: unused_docs + + A list of document names that are present, but not currently included in the + toctree. Use this setting to suppress the warning that is normally emitted + in that case. + +.. confval:: add_function_parentheses + + A boolean that decides whether parentheses are appended to function and + method role text (e.g. the content of ``:func:`input```) to signify that the + name is callable. Default is ``True``. + +.. confval:: add_module_names + + A boolean that decides whether module names are prepended to all + :term:`description unit` titles, e.g. for :dir:`function` directives. + Default is ``True``. + +.. confval:: show_authors + + A boolean that decides whether :dir:`moduleauthor` and :dir:`sectionauthor` + directives produce any output in the built files. + +.. confval:: pygments_style + + The style name to use for Pygments highlighting of source code. Default is + ``'sphinx'``, which is a builtin style designed to match Sphinx' default + style. + + +Options for HTML output +----------------------- + +These options influence HTML as well as HTML Help output, and other builders +that use Sphinx' HTMLWriter class. + +.. confval:: html_style + + The style sheet to use for HTML pages. A file of that name must exist either + in Sphinx' :file:`static/` path, or in one of the custom paths given in + :confval:`html_static_path`. Default is ``'default.css'``. + +.. confval:: html_static_path + + A list of paths that contain custom static files (such as style sheets or + script files). They are copied to the output directory after the builtin + static files, so a file named :file:`default.css` will overwrite the builtin + :file:`default.css`. + +.. confval:: html_last_updated_fmt + + If this is not the empty string, a 'Last updated on:' timestamp is inserted + at every page bottom, using the given :func:`strftime` format. Default is + ``'%b %d, %Y'``. + +.. confval:: html_use_smartypants + + If true, *SmartyPants* will be used to convert quotes and dashes to + typographically correct entities. Default: ``True``. + +.. confval:: html_index + + Content template for the index page, filename relative to this file. If this + is not the empty string, the "index" document will not be created from a + reStructuredText file but from this template. + +.. confval:: html_sidebars + + Custom sidebar templates, must be a dictionary that maps document names to + template names. + +.. confval:: html_additional_pages + + Additional templates that should be rendered to HTML pages, must be a + dictionary that maps document names to template names. + +.. confval:: html_copy_source + + If true, the reST sources are included in the HTML build as + :file:`_sources/{name}`. + +.. confval:: htmlhelp_basename + + Output file base name for HTML help builder. Default is ``'pydoc'``. + + +Options for LaTeX output +------------------------ + +These options influence LaTeX output. + +.. confval:: latex_paper_size + + The output paper size (``'letter'`` or ``'a4'``). Default is ``'letter'``. + +.. confval:: latex_font_size + + The font size ('10pt', '11pt' or '12pt'). Default is ``'10pt'``. + +.. confval:: latex_documents + + Grouping the document tree into LaTeX files. List of tuples (source start + file, target name, title, author, document class [howto/manual]). + + XXX expand. + +.. confval:: latex_appendices + + Documents to append as an appendix to all manuals. + +.. confval:: latex_preamble + + Additional LaTeX markup for the preamble. diff --git a/doc/contents.rst b/doc/contents.rst new file mode 100644 index 000000000..ef1bf717c --- /dev/null +++ b/doc/contents.rst @@ -0,0 +1,27 @@ +.. _contents: + +Sphinx documentation contents +============================= + +.. toctree:: + :maxdepth: 1 + + intro.rst + concepts.rst + rest.rst + markup.rst + builders.rst + config.rst + templating.rst + extensions.rst + + glossary.rst + + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` +* :ref:`glossary` diff --git a/doc/ext.py b/doc/ext.py new file mode 100644 index 000000000..581ea476a --- /dev/null +++ b/doc/ext.py @@ -0,0 +1,4 @@ +def setup(app): + app.add_description_unit('directive', 'dir', 'directive') + app.add_description_unit('role', 'role', 'role') + app.add_description_unit('confval', 'confval', 'configuration value') diff --git a/doc/extensions.rst b/doc/extensions.rst new file mode 100644 index 000000000..1bb52c4b5 --- /dev/null +++ b/doc/extensions.rst @@ -0,0 +1,110 @@ +.. _extensions: + +Sphinx Extensions +================= + +.. module:: sphinx.application + :synopsis: Application class and extensibility interface. + +Since many projects will need special features in their documentation, Sphinx is +designed to be extensible on several levels. + +First, you can add new :term:`builder`\s to support new output formats or +actions on the parsed documents. Then, it is possible to register custom +reStructuredText roles and directives, extending the markup. And finally, there +are so-called "hook points" at strategic places throughout the build process, +where an extension can register a hook and run specialized code. + +Each Sphinx extension is a Python module with at least a :func:`setup` function. +This function is called at initialization time with one argument, the +application object representing the Sphinx process. This application object has +the following public API: + +.. method:: Application.add_builder(builder) + + Register a new builder. *builder* must be a class that inherits from + :class:`~sphinx.builder.Builder`. + +.. method:: Application.add_config_value(name, default, rebuild_env) + + Register a configuration value. This is necessary for Sphinx to recognize + new values and set default values accordingly. The *name* should be prefixed + with the extension name, to avoid clashes. The *default* value can be any + Python object. The boolean value *rebuild_env* must be ``True`` if a change + in the setting only takes effect when a document is parsed -- this means that + the whole environment must be rebuilt. + +.. method:: Application.add_event(name) + + Register an event called *name*. + +.. method:: Application.add_node(node) + + Register a Docutils node class. This is necessary for Docutils internals. + It may also be used in the future to validate nodes in the parsed documents. + +.. method:: Application.add_directive(name, cls, content, arguments, **options) + + Register a Docutils directive. *name* must be the prospective directive + name, *func* the directive function (see the Docutils documentation - XXX + ref) for details about the signature and return value. *content*, + *arguments* and *options* are set as attributes on the function and determine + whether the directive has content, arguments and options, respectively. For + their exact meaning, please consult the Docutils documentation. + +.. method:: Application.add_role(name, role) + + Register a Docutils role. *name* must be the role name that occurs in the + source, *role* the role function (see the Docutils documentation on details). + +.. method:: Application.add_description_unit(directivename, rolename, indexdesc='', parse_node=None) + + XXX + +.. method:: Application.connect(event, callback) + + Register *callback* to be called when *event* is emitted. For details on + available core events and the arguments of callback functions, please see + :ref:`events`. + + The method returns a "listener ID" that can be used as an argument to + :meth:`disconnect`. + +.. method:: Application.disconnect(listener_id) + + Unregister callback *listener_id*. + +.. method:: Application.emit(event, *arguments) + + Emit *event* and pass *arguments* to the callback functions. Do not emit + core Sphinx events in extensions! + + +.. exception:: ExtensionError + + All these functions raise this exception if something went wrong with the + extension API. + +Examples of using the Sphinx extension API can be seen in the :mod:`sphinx.ext` +package. + + +.. _events: + +Sphinx core events +------------------ + +These events are known to the core: + +====================== =================================== ========= +Event name Emitted when Arguments +====================== =================================== ========= +``'builder-inited'`` the builder object has been created -none- +``'doctree-read'`` a doctree has been parsed and read *doctree* + by the environment, and is about to + be pickled +``'doctree-resolved'`` a doctree has been "resolved" by *doctree*, *docname* + the environment, that is, all + references and TOCs have been + inserted +====================== =================================== ========= diff --git a/doc/glossary.rst b/doc/glossary.rst new file mode 100644 index 000000000..662d0a9ca --- /dev/null +++ b/doc/glossary.rst @@ -0,0 +1,22 @@ +.. _glossary: + +Glossary +======== + +.. glossary:: + + builder + A class (inheriting from :class:`~sphinx.builder.Builder`) that takes + parsed documents and performs an action on them. Normally, builders + translate the documents to an output format, but it is also possible to + use the builder builders that e.g. check for broken links in the + documentation, or build coverage information. + + See :ref:`builders` for an overview over Sphinx' built-in builders. + + description unit + XXX + + documentation root + The directory which contains the documentation's :file:`conf.py` file and + is therefore seen as one Sphinx project. diff --git a/doc/intro.rst b/doc/intro.rst new file mode 100644 index 000000000..bf56c8c13 --- /dev/null +++ b/doc/intro.rst @@ -0,0 +1,11 @@ +Introduction +============ + + + +Prerequisites +------------- + + +Running a build +--------------- diff --git a/doc/markup.rst b/doc/markup.rst new file mode 100644 index 000000000..437dcc49f --- /dev/null +++ b/doc/markup.rst @@ -0,0 +1,835 @@ +.. highlight:: rest + :linenothreshold: 5 + +.. XXX missing: glossary + + +Sphinx Markup Constructs +======================== + +Sphinx adds a lot of new directives and interpreted text roles to standard reST +markup. This section contains the reference material for these facilities. + + +File-wide metadata +------------------ + +reST has the concept of "field lists"; these are a sequence of fields marked up +like this:: + + :Field name: Field content + +A field list at the very top of a file is parsed as the "docinfo", which in +normal documents can be used to record the author, date of publication and +other metadata. In Sphinx, the docinfo is used as metadata, too, but not +displayed in the output. + +At the moment, only one metadata field is recognized: + +``nocomments`` + If set, the web application won't display a comment form for a page generated + from this source file. + + +Meta-information markup +----------------------- + +.. directive:: sectionauthor + + Identifies the author of the current section. The argument should include + the author's name such that it can be used for presentation and email + address. The domain name portion of the address should be lower case. + Example:: + + .. sectionauthor:: Guido van Rossum + + By default, this markup isn't reflected in the output in any way (it helps + keep track of contributions), but you can set the configuration value + :confval:`show_authors` to True to make them produce a paragraph in the + output. + + +Module-specific markup +---------------------- + +The markup described in this section is used to provide information about a +module being documented. Each module should be documented in its own file. +Normally this markup appears after the title heading of that file; a typical +file might start like this:: + + :mod:`parrot` -- Dead parrot access + =================================== + + .. module:: parrot + :platform: Unix, Windows + :synopsis: Analyze and reanimate dead parrots. + .. moduleauthor:: Eric Cleese + .. moduleauthor:: John Idle + +As you can see, the module-specific markup consists of two directives, the +``module`` directive and the ``moduleauthor`` directive. + +.. directive:: module + + This directive marks the beginning of the description of a module (or package + submodule, in which case the name should be fully qualified, including the + package name). + + The ``platform`` option, if present, is a comma-separated list of the + platforms on which the module is available (if it is available on all + platforms, the option should be omitted). The keys are short identifiers; + examples that are in use include "IRIX", "Mac", "Windows", and "Unix". It is + important to use a key which has already been used when applicable. + + The ``synopsis`` option should consist of one sentence describing the + module's purpose -- it is currently only used in the Global Module Index. + + The ``deprecated`` option can be given (with no value) to mark a module as + deprecated; it will be designated as such in various locations then. + +.. directive:: moduleauthor + + The ``moduleauthor`` directive, which can appear multiple times, names the + authors of the module code, just like ``sectionauthor`` names the author(s) + of a piece of documentation. It too only produces output if the + :confval:`show_authors` configuration value is True. + + +.. note:: + + It is important to make the section title of a module-describing file + meaningful since that value will be inserted in the table-of-contents trees + in overview files. + + +Information units +----------------- + +There are a number of directives used to describe specific features provided by +modules. Each directive requires one or more signatures to provide basic +information about what is being described, and the content should be the +description. The basic version makes entries in the general index; if no index +entry is desired, you can give the directive option flag ``:noindex:``. The +following example shows all of the features of this directive type:: + + .. function:: spam(eggs) + ham(eggs) + :noindex: + + Spam or ham the foo. + +The signatures of object methods or data attributes should always include the +type name (``.. method:: FileInput.input(...)``), even if it is obvious from the +context which type they belong to; this is to enable consistent +cross-references. If you describe methods belonging to an abstract protocol, +such as "context managers", include a (pseudo-)type name too to make the +index entries more informative. + +The directives are: + +.. directive:: cfunction + + Describes a C function. The signature should be given as in C, e.g.:: + + .. cfunction:: PyObject* PyType_GenericAlloc(PyTypeObject *type, Py_ssize_t nitems) + + This is also used to describe function-like preprocessor macros. The names + of the arguments should be given so they may be used in the description. + + Note that you don't have to backslash-escape asterisks in the signature, + as it is not parsed by the reST inliner. + +.. directive:: cmember + + Describes a C struct member. Example signature:: + + .. cmember:: PyObject* PyTypeObject.tp_bases + + The text of the description should include the range of values allowed, how + the value should be interpreted, and whether the value can be changed. + References to structure members in text should use the ``member`` role. + +.. directive:: cmacro + + Describes a "simple" C macro. Simple macros are macros which are used + for code expansion, but which do not take arguments so cannot be described as + functions. This is not to be used for simple constant definitions. Examples + of its use in the Python documentation include :cmacro:`PyObject_HEAD` and + :cmacro:`Py_BEGIN_ALLOW_THREADS`. + +.. directive:: ctype + + Describes a C type. The signature should just be the type name. + +.. directive:: cvar + + Describes a global C variable. The signature should include the type, such + as:: + + .. cvar:: PyObject* PyClass_Type + +.. directive:: data + + Describes global data in a module, including both variables and values used + as "defined constants." Class and object attributes are not documented + using this environment. + +.. directive:: exception + + Describes an exception class. The signature can, but need not include + parentheses with constructor arguments. + +.. directive:: function + + Describes a module-level function. The signature should include the + parameters, enclosing optional parameters in brackets. Default values can be + given if it enhances clarity. For example:: + + .. function:: Timer.repeat([repeat=3[, number=1000000]]) + + Object methods are not documented using this directive. Bound object methods + placed in the module namespace as part of the public interface of the module + are documented using this, as they are equivalent to normal functions for + most purposes. + + The description should include information about the parameters required and + how they are used (especially whether mutable objects passed as parameters + are modified), side effects, and possible exceptions. A small example may be + provided. + +.. directive:: class + + Describes a class. The signature can include parentheses with parameters + which will be shown as the constructor arguments. + +.. directive:: attribute + + Describes an object data attribute. The description should include + information about the type of the data to be expected and whether it may be + changed directly. + +.. directive:: method + + Describes an object method. The parameters should not include the ``self`` + parameter. The description should include similar information to that + described for ``function``. + +.. directive:: opcode + + Describes a Python bytecode instruction (this is not very useful for projects + other than Python itself). + +.. directive:: cmdoption + + Describes a command line option or switch. Option argument names should be + enclosed in angle brackets. Example:: + + .. cmdoption:: -m + + Run a module as a script. + +.. directive:: envvar + + Describes an environment variable that the documented code uses or defines. + + +There is also a generic version of these directives: + +.. directive:: describe + + This directive produces the same formatting as the specific ones explained + above but does not create index entries or cross-referencing targets. It is + used, for example, to describe the directives in this document. Example:: + + .. describe:: opcode + + Describes a Python bytecode instruction. + + +Showing code examples +--------------------- + +Examples of Python source code or interactive sessions are represented using +standard reST literal blocks. They are started by a ``::`` at the end of the +preceding paragraph and delimited by indentation. + +Representing an interactive session requires including the prompts and output +along with the Python code. No special markup is required for interactive +sessions. After the last line of input or output presented, there should not be +an "unused" primary prompt; this is an example of what *not* to do:: + + >>> 1 + 1 + 2 + >>> + +Syntax highlighting is handled in a smart way: + +* There is a "highlighting language" for each source file. Per default, + this is ``'python'`` as the majority of files will have to highlight Python + snippets. + +* Within Python highlighting mode, interactive sessions are recognized + automatically and highlighted appropriately. + +* The highlighting language can be changed using the ``highlightlang`` + directive, used as follows:: + + .. highlightlang:: c + + This language is used until the next ``highlightlang`` directive is + encountered. + +* The valid values for the highlighting language are: + + * ``python`` (the default) + * ``c`` + * ``rest`` + * ``none`` (no highlighting) + +* If highlighting with the current language fails, the block is not highlighted + in any way. + +Longer displays of verbatim text may be included by storing the example text in +an external file containing only plain text. The file may be included using the +``literalinclude`` directive. [1]_ For example, to include the Python source file +:file:`example.py`, use:: + + .. literalinclude:: example.py + +The file name is relative to the current file's path. Documentation-specific +include files should be placed in the ``Doc/includes`` subdirectory. + + +Inline markup +------------- + +As said before, Sphinx uses interpreted text roles to insert semantic markup in +documents. + +Variable names are an exception, they should be marked simply with ``*var*``. + +For all other roles, you have to write ``:rolename:`content```. + +.. note:: + + For all cross-referencing roles, if you prefix the content with ``!``, no + reference/hyperlink will be created. + +The following roles refer to objects in modules and are possibly hyperlinked if +a matching identifier is found: + +.. role:: mod + + The name of a module; a dotted name may be used. This should also be used for + package names. + +.. role:: func + + The name of a Python function; dotted names may be used. The role text + should include trailing parentheses to enhance readability. The parentheses + are stripped when searching for identifiers. + +.. role:: data + + The name of a module-level variable. + +.. role:: const + + The name of a "defined" constant. This may be a C-language ``#define`` + or a Python variable that is not intended to be changed. + +.. role:: class + + A class name; a dotted name may be used. + +.. role:: meth + + The name of a method of an object. The role text should include the type + name, method name and the trailing parentheses. A dotted name may be used. + +.. role:: attr + + The name of a data attribute of an object. + +.. role:: exc + + The name of an exception. A dotted name may be used. + +The name enclosed in this markup can include a module name and/or a class name. +For example, ``:func:`filter``` could refer to a function named ``filter`` in +the current module, or the built-in function of that name. In contrast, +``:func:`foo.filter``` clearly refers to the ``filter`` function in the ``foo`` +module. + +Normally, names in these roles are searched first without any further +qualification, then with the current module name prepended, then with the +current module and class name (if any) prepended. If you prefix the name with a +dot, this order is reversed. For example, in the documentation of the +:mod:`codecs` module, ``:func:`open``` always refers to the built-in function, +while ``:func:`.open``` refers to :func:`codecs.open`. + +A similar heuristic is used to determine whether the name is an attribute of +the currently documented class. + +The following roles create cross-references to C-language constructs if they +are defined in the API documentation: + +.. role:: cdata + + The name of a C-language variable. + +.. role:: cfunc + + The name of a C-language function. Should include trailing parentheses. + +.. role:: cmacro + + The name of a "simple" C macro, as defined above. + +.. role:: ctype + + The name of a C-language type. + + +The following roles do possibly create a cross-reference, but do not refer +to objects: + +.. role:: token + + The name of a grammar token (used in the reference manual to create links + between production displays). + +.. role:: keyword + + The name of a keyword in Python. This creates a link to a reference label + with that name, if it exists. + + +The following role creates a cross-reference to the term in the glossary: + +.. role:: term + + Reference to a term in the glossary. The glossary is created using the + ``glossary`` directive containing a definition list with terms and + definitions. It does not have to be in the same file as the ``term`` markup, + for example the Python docs have one global glossary in the ``glossary.rst`` + file. + + If you use a term that's not explained in a glossary, you'll get a warning + during build. + +--------- + +The following roles don't do anything special except formatting the text +in a different style: + +.. role:: command + + The name of an OS-level command, such as ``rm``. + +.. role:: dfn + + Mark the defining instance of a term in the text. (No index entries are + generated.) + +.. role:: envvar + + An environment variable. Index entries are generated. + +.. role:: file + + The name of a file or directory. Within the contents, you can use curly + braces to indicate a "variable" part, for example:: + + ... is installed in :file:`/usr/lib/python2.{x}/site-packages` ... + + In the built documentation, the ``x`` will be displayed differently to + indicate that it is to be replaced by the Python minor version. + +.. role:: guilabel + + Labels presented as part of an interactive user interface should be marked + using ``guilabel``. This includes labels from text-based interfaces such as + those created using :mod:`curses` or other text-based libraries. Any label + used in the interface should be marked with this role, including button + labels, window titles, field names, menu and menu selection names, and even + values in selection lists. + +.. role:: kbd + + Mark a sequence of keystrokes. What form the key sequence takes may depend + on platform- or application-specific conventions. When there are no relevant + conventions, the names of modifier keys should be spelled out, to improve + accessibility for new users and non-native speakers. For example, an + *xemacs* key sequence may be marked like ``:kbd:`C-x C-f```, but without + reference to a specific application or platform, the same sequence should be + marked as ``:kbd:`Control-x Control-f```. + +.. role:: mailheader + + The name of an RFC 822-style mail header. This markup does not imply that + the header is being used in an email message, but can be used to refer to any + header of the same "style." This is also used for headers defined by the + various MIME specifications. The header name should be entered in the same + way it would normally be found in practice, with the camel-casing conventions + being preferred where there is more than one common usage. For example: + ``:mailheader:`Content-Type```. + +.. role:: makevar + + The name of a :command:`make` variable. + +.. role:: manpage + + A reference to a Unix manual page including the section, + e.g. ``:manpage:`ls(1)```. + +.. role:: menuselection + + Menu selections should be marked using the ``menuselection`` role. This is + used to mark a complete sequence of menu selections, including selecting + submenus and choosing a specific operation, or any subsequence of such a + sequence. The names of individual selections should be separated by + ``-->``. + + For example, to mark the selection "Start > Programs", use this markup:: + + :menuselection:`Start --> Programs` + + When including a selection that includes some trailing indicator, such as the + ellipsis some operating systems use to indicate that the command opens a + dialog, the indicator should be omitted from the selection name. + +.. role:: mimetype + + The name of a MIME type, or a component of a MIME type (the major or minor + portion, taken alone). + +.. role:: newsgroup + + The name of a Usenet newsgroup. + +.. role:: option + + A command-line option to an executable program. The leading hyphen(s) must + be included. + +.. role:: program + + The name of an executable program. This may differ from the file name for + the executable for some platforms. In particular, the ``.exe`` (or other) + extension should be omitted for Windows programs. + +.. role:: regexp + + A regular expression. Quotes should not be included. + +.. role:: samp + + A piece of literal text, such as code. Within the contents, you can use + curly braces to indicate a "variable" part, as in ``:file:``. + + If you don't need the "variable part" indication, use the standard + ````code```` instead. + +.. role:: var + + A Python or C variable or parameter name. + + +The following roles generate external links: + +.. role:: pep + + A reference to a Python Enhancement Proposal. This generates appropriate + index entries. The text "PEP *number*\ " is generated; in the HTML output, + this text is a hyperlink to an online copy of the specified PEP. + +.. role:: rfc + + A reference to an Internet Request for Comments. This generates appropriate + index entries. The text "RFC *number*\ " is generated; in the HTML output, + this text is a hyperlink to an online copy of the specified RFC. + + +Note that there are no special roles for including hyperlinks as you can use +the standard reST markup for that purpose. + + +.. _doc-ref-role: + +Cross-linking markup +-------------------- + +.. XXX add new :ref: syntax alternative + +To support cross-referencing to arbitrary sections in the documentation, the +standard reST labels are "abused" a bit: Every label must precede a section +title; and every label name must be unique throughout the entire documentation +source. + +You can then reference to these sections using the ``:ref:`label-name``` role. + +Example:: + + .. _my-reference-label: + + Section to cross-reference + -------------------------- + + This is the text of the section. + + It refers to the section itself, see :ref:`my-reference-label`. + +The ``:ref:`` invocation is replaced with the section title. + + +Paragraph-level markup +---------------------- + +These directives create short paragraphs and can be used inside information +units as well as normal text: + +.. directive:: note + + An especially important bit of information about an API that a user should be + aware of when using whatever bit of API the note pertains to. The content of + the directive should be written in complete sentences and include all + appropriate punctuation. + + Example:: + + .. note:: + + This function is not suitable for sending spam e-mails. + +.. directive:: warning + + An important bit of information about an API that a user should be very aware + of when using whatever bit of API the warning pertains to. The content of + the directive should be written in complete sentences and include all + appropriate punctuation. This differs from ``note`` in that it is recommended + over ``note`` for information regarding security. + +.. directive:: versionadded + + This directive documents the version of the project which added the described + feature to the library or C API. When this applies to an entire module, it + should be placed at the top of the module section before any prose. + + The first argument must be given and is the version in question; you can add + a second argument consisting of a *brief* explanation of the change. + + Example:: + + .. versionadded:: 2.5 + The `spam` parameter. + + Note that there must be no blank line between the directive head and the + explanation; this is to make these blocks visually continuous in the markup. + +.. directive:: versionchanged + + Similar to ``versionadded``, but describes when and what changed in the named + feature in some way (new parameters, changed side effects, etc.). + +-------------- + +.. directive:: seealso + + Many sections include a list of references to module documentation or + external documents. These lists are created using the ``seealso`` directive. + + The ``seealso`` directive is typically placed in a section just before any + sub-sections. For the HTML output, it is shown boxed off from the main flow + of the text. + + The content of the ``seealso`` directive should be a reST definition list. + Example:: + + .. seealso:: + + Module :mod:`zipfile` + Documentation of the :mod:`zipfile` standard module. + + `GNU tar manual, Basic Tar Format `_ + Documentation for tar archive files, including GNU tar extensions. + +.. directive:: rubric + + This directive creates a paragraph heading that is not used to create a + table of contents node. It is currently used for the "Footnotes" caption. + +.. directive:: centered + + This directive creates a centered boldfaced paragraph. Use it as follows:: + + .. centered:: + + Paragraph contents. + + +Table-of-contents markup +------------------------ + +Since reST does not have facilities to interconnect several documents, or split +documents into multiple output files, Sphinx uses a custom directive to add +relations between the single files the documentation is made of, as well as +tables of contents. The ``toctree`` directive is the central element. + +.. directive:: toctree + + This directive inserts a "TOC tree" at the current location, using the + individual TOCs (including "sub-TOC trees") of the files given in the + directive body. A numeric ``maxdepth`` option may be given to indicate the + depth of the tree; by default, all levels are included. + + Consider this example (taken from the library reference index):: + + .. toctree:: + :maxdepth: 2 + + intro.rst + strings.rst + datatypes.rst + numeric.rst + (many more files listed here) + + This accomplishes two things: + + * Tables of contents from all those files are inserted, with a maximum depth + of two, that means one nested heading. ``toctree`` directives in those + files are also taken into account. + * Sphinx knows that the relative order of the files ``intro.rst``, + ``strings.rst`` and so forth, and it knows that they are children of the + shown file, the library index. From this information it generates "next + chapter", "previous chapter" and "parent chapter" links. + + In the end, all files included in the build process must occur in one + ``toctree`` directive; Sphinx will emit a warning if it finds a file that is + not included, because that means that this file will not be reachable through + standard navigation. + + The special file ``contents.rst`` at the root of the source directory is the + "root" of the TOC tree hierarchy; from it the "Contents" page is generated. + + +Index-generating markup +----------------------- + +Sphinx automatically creates index entries from all information units (like +functions, classes or attributes) like discussed before. + +However, there is also an explicit directive available, to make the index more +comprehensive and enable index entries in documents where information is not +mainly contained in information units, such as the language reference. + +The directive is ``index`` and contains one or more index entries. Each entry +consists of a type and a value, separated by a colon. + +For example:: + + .. index:: + single: execution; context + module: __main__ + module: sys + triple: module; search; path + +This directive contains five entries, which will be converted to entries in the +generated index which link to the exact location of the index statement (or, in +case of offline media, the corresponding page number). + +The possible entry types are: + +single + Creates a single index entry. Can be made a subentry by separating the + subentry text with a semicolon (this notation is also used below to describe + what entries are created). +pair + ``pair: loop; statement`` is a shortcut that creates two index entries, + namely ``loop; statement`` and ``statement; loop``. +triple + Likewise, ``triple: module; search; path`` is a shortcut that creates three + index entries, which are ``module; search path``, ``search; path, module`` and + ``path; module search``. +module, keyword, operator, object, exception, statement, builtin + These all create two index entries. For example, ``module: hashlib`` creates + the entries ``module; hashlib`` and ``hashlib; module``. + +For index directives containing only "single" entries, there is a shorthand +notation:: + + .. index:: BNF, grammar, syntax, notation + +This creates four index entries. + + +Grammar production displays +--------------------------- + +Special markup is available for displaying the productions of a formal grammar. +The markup is simple and does not attempt to model all aspects of BNF (or any +derived forms), but provides enough to allow context-free grammars to be +displayed in a way that causes uses of a symbol to be rendered as hyperlinks to +the definition of the symbol. There is this directive: + +.. directive:: productionlist + + This directive is used to enclose a group of productions. Each production is + given on a single line and consists of a name, separated by a colon from the + following definition. If the definition spans multiple lines, each + continuation line must begin with a colon placed at the same column as in the + first line. + + Blank lines are not allowed within ``productionlist`` directive arguments. + + The definition can contain token names which are marked as interpreted text + (e.g. ``sum ::= `integer` "+" `integer```) -- this generates cross-references + to the productions of these tokens. + + Note that no further reST parsing is done in the production, so that you + don't have to escape ``*`` or ``|`` characters. + + +.. XXX describe optional first parameter + +The following is an example taken from the Python Reference Manual:: + + .. productionlist:: + try_stmt: try1_stmt | try2_stmt + try1_stmt: "try" ":" `suite` + : ("except" [`expression` ["," `target`]] ":" `suite`)+ + : ["else" ":" `suite`] + : ["finally" ":" `suite`] + try2_stmt: "try" ":" `suite` + : "finally" ":" `suite` + + +Substitutions +------------- + +The documentation system provides three substitutions that are defined by default. +They are set in the build configuration file, see :ref:`doc-build-config`. + +.. describe:: |release| + + Replaced by the project release the documentation refers to. This is meant + to be the full version string including alpha/beta/release candidate tags, + e.g. ``2.5.2b3``. + +.. describe:: |version| + + Replaced by the project version the documentation refers to. This is meant to + consist only of the major and minor version parts, e.g. ``2.5``, even for + version 2.5.1. + +.. describe:: |today| + + Replaced by either today's date, or the date set in the build configuration + file. Normally has the format ``April 14, 2007``. + + +.. rubric:: Footnotes + +.. [1] There is a standard ``.. include`` directive, but it raises errors if the + file is not found. This one only emits a warning. diff --git a/doc/rest.rst b/doc/rest.rst new file mode 100644 index 000000000..988e46e59 --- /dev/null +++ b/doc/rest.rst @@ -0,0 +1,251 @@ +.. highlightlang:: rest + +reStructuredText Primer +======================= + +This section is a brief introduction to reStructuredText (reST) concepts and +syntax, intended to provide authors with enough information to author documents +productively. Since reST was designed to be a simple, unobtrusive markup +language, this will not take too long. + +.. seealso:: + + The authoritative `reStructuredText User + Documentation `_. + + +Paragraphs +---------- + +The paragraph is the most basic block in a reST document. Paragraphs are simply +chunks of text separated by one or more blank lines. As in Python, indentation +is significant in reST, so all lines of the same paragraph must be left-aligned +to the same level of indentation. + + +Inline markup +------------- + +The standard reST inline markup is quite simple: use + +* one asterisk: ``*text*`` for emphasis (italics), +* two asterisks: ``**text**`` for strong emphasis (boldface), and +* backquotes: ````text```` for code samples. + +If asterisks or backquotes appear in running text and could be confused with +inline markup delimiters, they have to be escaped with a backslash. + +Be aware of some restrictions of this markup: + +* it may not be nested, +* content may not start or end with whitespace: ``* text*`` is wrong, +* it must be separated from surrounding text by non-word characters. Use a + backslash escaped space to work around that: ``thisis\ *one*\ word``. + +These restrictions may be lifted in future versions of the docutils. + +reST also allows for custom "interpreted text roles"', which signify that the +enclosed text should be interpreted in a specific way. Sphinx uses this to +provide semantic markup and cross-referencing of identifiers, as described in +the appropriate section. The general syntax is ``:rolename:`content```. + + +Lists and Quotes +---------------- + +List markup is natural: just place an asterisk at the start of a paragraph and +indent properly. The same goes for numbered lists; they can also be +autonumbered using a ``#`` sign:: + + * This is a bulleted list. + * It has two items, the second + item uses two lines. + + 1. This is a numbered list. + 2. It has two items too. + + #. This is a numbered list. + #. It has two items too. + +Note that Sphinx disables the use of enumerated lists introduced by alphabetic +or roman numerals, such as :: + + A. First item + B. Second item + + +Nested lists are possible, but be aware that they must be separated from the +parent list items by blank lines:: + + * this is + * a list + + * with a nested list + * and some subitems + + * and here the parent list continues + +Definition lists are created as follows:: + + term (up to a line of text) + Definition of the term, which must be indented + + and can even consist of multiple paragraphs + + next term + Description. + + +Paragraphs are quoted by just indenting them more than the surrounding +paragraphs. + + +Source Code +----------- + +Literal code blocks are introduced by ending a paragraph with the special marker +``::``. The literal block must be indented, to be able to include blank lines:: + + This is a normal text paragraph. The next paragraph is a code sample:: + + It is not processed in any way, except + that the indentation is removed. + + It can span multiple lines. + + This is a normal text paragraph again. + +The handling of the ``::`` marker is smart: + +* If it occurs as a paragraph of its own, that paragraph is completely left + out of the document. +* If it is preceded by whitespace, the marker is removed. +* If it is preceded by non-whitespace, the marker is replaced by a single + colon. + +That way, the second sentence in the above example's first paragraph would be +rendered as "The next paragraph is a code sample:". + + +Hyperlinks +---------- + +External links +^^^^^^^^^^^^^^ + +Use ```Link text `_`` for inline web links. If the link text +should be the web address, you don't need special markup at all, the parser +finds links and mail addresses in ordinary text. + +Internal links +^^^^^^^^^^^^^^ + +Internal linking is done via a special reST role, see the section on specific +markup, :ref:`doc-ref-role`. + + +Sections +-------- + +Section headers are created by underlining (and optionally overlining) the +section title with a punctuation character, at least as long as the text:: + + ================= + This is a heading + ================= + +Normally, there are no heading levels assigned to certain characters as the +structure is determined from the succession of headings. However, for the +Python documentation, this convention is used which you may follow: + +* ``#`` with overline, for parts +* ``*`` with overline, for chapters +* ``=``, for sections +* ``-``, for subsections +* ``^``, for subsubsections +* ``"``, for paragraphs + + +Explicit Markup +--------------- + +"Explicit markup" is used in reST for most constructs that need special +handling, such as footnotes, specially-highlighted paragraphs, comments, and +generic directives. + +An explicit markup block begins with a line starting with ``..`` followed by +whitespace and is terminated by the next paragraph at the same level of +indentation. (There needs to be a blank line between explicit markup and normal +paragraphs. This may all sound a bit complicated, but it is intuitive enough +when you write it.) + + +Directives +---------- + +A directive is a generic block of explicit markup. Besides roles, it is one of +the extension mechanisms of reST, and Sphinx makes heavy use of it. + +Basically, a directive consists of a name, arguments, options and content. (Keep +this terminology in mind, it is used in the next chapter describing custom +directives.) Looking at this example, :: + + .. function:: foo(x) + foo(y, z) + :bar: no + + Return a line of text input from the user. + +``function`` is the directive name. It is given two arguments here, the +remainder of the first line and the second line, as well as one option ``bar`` +(as you can see, options are given in the lines immediately following the +arguments and indicated by the colons). + +The directive content follows after a blank line and is indented relative to the +directive start. + + +Footnotes +--------- + +For footnotes, use ``[#]_`` to mark the footnote location, and add the footnote +body at the bottom of the document after a "Footnotes" rubric heading, like so:: + + Lorem ipsum [#]_ dolor sit amet ... [#]_ + + .. rubric:: Footnotes + + .. [#] Text of the first footnote. + .. [#] Text of the second footnote. + +You can also explicitly number the footnotes for better context. + + +Comments +-------- + +Every explicit markup block which isn't a valid markup construct (like the +footnotes above) is regarded as a comment. + + +Source encoding +--------------- + +Since the easiest way to include special characters like em dashes or copyright +signs in reST is to directly write them as Unicode characters, one has to +specify an encoding: + +All documentation source files must be in UTF-8 encoding, and the HTML +documents written from them will be in that encoding as well. + + +Gotchas +------- + +There are some problems one commonly runs into while authoring reST documents: + +* **Separation of inline markup:** As said above, inline markup spans must be + separated from the surrounding text by non-word characters, you have to use + an escaped space to get around that. + +.. XXX more? diff --git a/doc/templating.rst b/doc/templating.rst new file mode 100644 index 000000000..eb3a3bf6c --- /dev/null +++ b/doc/templating.rst @@ -0,0 +1,4 @@ +.. _templating: + +Templating +==========