doc.pdf

(214 KB) Pobierz
Documenting Python
DocumentingPython
Release2.5
FredL.Drake,Jr.
19thSeptember,2006
PythonLabs
Email: fdrake@acm.org
Abstract
ThePythonlanguagehasasubstantialbodyofdocumentation,muchofitcontributedbyvariousauthors.The
markupusedforthePythondocumentationisbasedonL A T E Xandrequiresasignificantsetofmacroswritten
specificallyfordocumentingPython.ThisdocumentdescribesthemacrosintroducedtosupportPythondocu-
mentationandhowtheyshouldbeusedtosupportawiderangeofoutputformats.
ThisdocumentdescribesthedocumentclassesandspecialmarkupusedinthePythondocumentation.Au-
thorsmayusethisguide,inconjunctionwiththetemplatefilesprovidedwiththedistribution,tocreateor
maintainwholedocumentsorsections.
Ifyou’reinterestedincontributingtoPython’sdocumentation,there’snoneedtolearnL A T E Xifyou’renotso
inclined;plaintextcontributionsaremorethanwelcomeaswell.
Contents
1Introduction
2
2DirectoryStructure
2
3StyleGuide
3
4L A T E XPrimer 4
4.1Syntax ................................................ 4
4.2HierarchicalStructure ........................................ 6
4.3CommonEnvironments ....................................... 7
5DocumentClasses
7
6SpecialMarkupConstructs 8
6.1MarkupforthePreamble ....................................... 8
6.2Meta-informationMarkup ...................................... 8
6.3InformationUnits ........................................... 8
6.4ShowingCodeExamples ....................................... 10
6.5InlineMarkup ............................................ 10
6.6MiscellaneousTextMarkup ..................................... 14
6.7Module-specificMarkup ....................................... 14
6.8Library-levelMarkup ......................................... 15
6.9TableMarkup ............................................. 15
6.10ReferenceListMarkup ........................................ 17
6.11Index-generatingMarkup ...................................... 18
6.12GrammarProductionDisplays .................................... 20
6.13GraphicalInterfaceComponents ................................... 20
7ProcessingTools 21
7.1ExternalTools ............................................ 21
7.2InternalTools ............................................. 22
7.3WorkingonCygwin ......................................... 22
8IncludingGraphics
23
9FutureDirections 24
9.1StructuredDocumentation ...................................... 24
9.2DiscussionForums .......................................... 25
Index
26
1Introduction
Python’sdocumentationhaslongbeenconsideredtobegoodforafreeprogramminglanguage.Thereareanum-
berofreasonsforthis,themostimportantbeingtheearlycommitmentofPython’screator,GuidovanRossum,to
providingdocumentationonthelanguageanditslibraries,andthecontinuinginvolvementoftheusercommunity
inprovidingassistanceforcreatingandmaintainingdocumentation.
Theinvolvementofthecommunitytakesmanyforms,fromauthoringtobugreportstojustplaincomplaining
whenthedocumentationcouldbemorecompleteoreasiertouse.Alloftheseformsofinputfromthecommunity
haveprovedusefulduringthetimeI’vebeeninvolvedinmaintainingthedocumentation.
ThisdocumentisaimedatauthorsandpotentialauthorsofdocumentationforPython.Morespecifically,itisfor
peoplecontributingtothestandarddocumentationanddevelopingadditionaldocumentsusingthesametoolsas
thestandarddocuments.ThisguidewillbelessusefulforauthorsusingthePythondocumentationtoolsfortopics
otherthanPython,andlessusefulstillforauthorsnotusingthetoolsatall.
ThematerialinthisguideisintendedtoassistauthorsusingthePythondocumentationtools.Itincludesinfor-
mationonthesourcedistributionofthestandarddocumentation,adiscussionofthedocumenttypes,reference
materialonthemarkupdefinedinthedocumentclasses,alistoftheexternaltoolsneededforprocessingdocu-
ments,andreferencematerialonthetoolsprovidedwiththedocumentationresources.Attheend,thereisalsoa
sectiondiscussingfuturedirectionsforthePythondocumentationandwheretoturnformoreinformation.
IfyourinterestisincontributingtothePythondocumentation,butyoudon’thavethetimeorinclinationto
learnL A T E Xandthemarkupstructuresdocumentedhere,there’sawelcomingplaceforyouamongthePython
contributorsaswell.Anytimeyoufeelthatyoucanclarifyexistingdocumentationorprovidedocumentation
that’smissing,theexistingdocumentationteamwillgladlyworkwithyoutointegrateyourtext,dealingwiththe
markupforyou.Pleasedon’tletthematerialinthisdocumentstandbetweenthedocumentationandyourdesire
tohelpout!
2DirectoryStructure
ThesourcedistributionforthestandardPythondocumentationcontainsalargenumberofdirectories.While
third-partydocumentsdonotneedtobeplacedintothisstructureorneedtobeplacedwithinasimilarstructure,
itcanbehelpfultoknowwheretolookforexamplesandtoolswhendevelopingnewdocumentsusingthePython
documentationtools.Thissectiondescribesthisdirectorystructure.
ThedocumentationsourcesareusuallyplacedwithinthePythonsourcedistributionasthetop-leveldirectory
‘ Doc/ ’,butarenotdependentonthePythonsourcedistributioninanyway.
The‘ Doc/ ’directorycontainsafewfilesandseveralsubdirectories.Thefilesaremostlyself-explanatory,including
a‘ README ’anda‘ Makefile ’.Thedirectoriesfallintothreecategories:
DocumentSources
2
2DirectoryStructure
1135624.001.png
 
TheL A T E Xsourcesforeachdocumentareplacedinaseparatedirectory.Thesedirectoriesaregivenshort
nameswhichvaguelyindicatethedocumentineach:
Format-SpecificOutput
Mostoutputformatshaveadirectorywhichcontainsa‘ Makefile ’whichcontrolsthegenerationofthat
formatandprovidesstoragefortheformatteddocuments.Theonlyvariationswithinthiscategoryare
thePortableDocumentFormat(PDF)andPostScriptversionsareplacedinthedirectories‘ paper-a4/ ’and
‘ paper-letter/ ’(thiscausesallthetemporaryfilescreatedbyL A T E Xtobekeptinthesameplaceforeach
papersize,wheretheycanbemoreeasilyignored).
Directory OutputFormats
html/ HTMLoutput
info/ GNUinfooutput
isilo/ iSilo documents(forPalmOSdevices)
paper-a4/ PDFandPostScript,A4paper
paper-letter/ PDFandPostScript,US-Letterpaper
SupplementalFiles
Someadditionaldirectoriesareusedtostoresupplementalfilesusedforthevariousprocesses.Directories
areincludedforthesharedL A T E Xdocumentclasses,theL A T E X2HTMLsupport,templatefilesforvarious
documentcomponents,andthescriptsusedtoperformvariousstepsintheformattingprocesses.
Directory Contents
commontex/ Documentcontentsharedamongdocuments
perl/ SupportforL A T E X2HTMLprocessing
templates/ Examplefilesforsourcedocuments
texinputs/ StyleimplementationforL A T E X
tools/ Customprocessingscripts
3StyleGuide
ThePythondocumentationshouldfollowthe ApplePublicationsStyleGuide whereverpossible.Thisparticular
styleguidewasselectedmostlybecauseitseemsreasonableandiseasytogetonline.
TopicswhicharenotcoveredintheApple’sstyleguidewillbediscussedinthisdocumentifnecessary.
FootnotesaregenerallydiscouragedduetothepainofusingfootnotesintheHTMLconversionofdocuments.
Footnotesmaybeusedwhentheyarethebestwaytopresentspecificinformation.Whenafootnotereference
isaddedattheendofthesentence,itshouldfollowthesentence-endingpunctuation.TheL A T E Xmarkupshould
appearsomethinglikethis:
Thissentencehasafootnotereference.%
\footnote{Thisisthefootnotetext.}
Footnotesmayappearinthemiddleofsentenceswhereappropriate.
3
1135624.002.png 1135624.003.png
ManyspecialnamesareusedinthePythondocumentation,includingthenamesofoperatingsystems,program-
minglanguages,standardsbodies,andthelike.ManyofthesewereassignedL A T E Xmacrosatsomepointinthe
distantpast,andthesemacroslivedonlongpasttheirusefulness.Inthecurrentmarkup,mostoftheseentities
arenotassignedanyspecialmarkup,butthepreferredspellingsaregivenheretoaidauthorsinmaintainingthe
consistencyofpresentationinthePythondocumentation.
Othertermsandwordsdeservespecialmentionaswell;theseconventionsshouldbeusedtoensureconsistency
throughoutthedocumentation:
CPUFor“centralprocessingunit.”Manystyleguidessaythisshouldbespelledoutonthefirstuse(andifyou
mustuseit,doso!).ForthePythondocumentation,thisabbreviationshouldbeavoidedsincethere’sno
reasonablewaytopredictwhichoccurrencewillbethefirstseenbythereader.Itisbettertousetheword
“processor”instead.
POSIXThenameassignedtoaparticulargroupofstandards.Thisisalwaysuppercase.Usethemacro \POSIX
torepresentthisname.
PythonThenameofourfavoriteprogramminglanguageisalwayscapitalized.
UnicodeThenameofacharactersetandmatchingencoding.Thisisalwayswrittencapitalized.
U NIX ThenameoftheoperatingsystemdevelopedatAT&TBellLabsintheearly1970s.Usethemacro \UNIX
tousethisname.
4L A T E XPrimer
ThissectionisabriefintroductiontoL A T E Xconceptsandsyntax,toprovideauthorsenoughinformationtoau-
thordocumentsproductivelywithouthavingtobecome“T E Xnicians.”Thisdoesnotteacheverythingneededto
knowaboutwritingL A T E XforPythondocumentation;manyofthestandard“environments”arenotdescribedhere
(thoughyouwilllearnhowtomarksomethingasanenvironment).
PerhapsthemostimportantconcepttokeepinmindwhilemarkingupPythondocumentationisthatwhileT E X
isunstructured,L A T E XwasdesignedasalayerontopofT E Xwhichspecificallysupportsstructuredmarkup.The
Python-specificmarkupisintendedtoextendthestructureprovidedbystandardL A T E Xdocumentclassestosupport
additionalinformationspecifictoPython.
L A T E Xdocumentscontaintwoparts:thepreambleandthebody.Thepreambleisusedtospecifycertainmetadata
aboutthedocumentitself,suchasthetitle,thelistofauthors,thedate,andtheclassthedocumentbelongs
to.Additionalinformationusedtocontrolindexgenerationandtheuseofbibliographicdatabasescanalsobe
placedinthepreamble.Formostauthors,thepreamblecanbemosteasilycreatedbycopyingitfromanexisting
documentandmodifyingafewkeypiecesofinformation.
Theclassofadocumentisusedtoplaceadocumentwithinabroadcategoryofdocumentsandsetsomefunda-
mentalformattingproperties.ForPythondocumentation,twoclassesareused:the manual classandthe howto
class.TheseclassesalsodefinetheadditionalmarkupusedtodocumentPythonconceptsandstructures.Spe-
cificinformationabouttheseclassesisprovidedinsection5,“DocumentClasses,”below.Thefirstthinginthe
preambleisthedeclarationofthedocument’sclass.
Aftertheclassdeclaration,anumberofmacrosareusedtoprovidefurtherinformationaboutthedocumentand
setupanyadditionalmarkupthatisneeded.Nooutputisgeneratedfromthepreamble;itisanerrortoinclude
freetextinthepreamblebecauseitwouldcauseoutput.
Thedocumentbodyfollowsthepreamble.Thiscontainsalltheprintedcomponentsofthedocumentmarked
upstructurally.GenericL A T E Xstructuresincludehierarchicalsections,numberedandbulletedlists,andspecial
structuresforthedocumentabstractandindexes.
4.1Syntax
TherearesomethingsthatanauthorofPythondocumentationneedstoknowaboutL A T E Xsyntax.
4
4L A T E XPrimer
Acommentisstartedbythe“percent”character(‘ % ’)andcontinuesthroughtheendofthelineandallleading
whitespaceonthefollowingline.ThisisalittledifferentfromanyprogramminglanguageIknowof,soan
exampleisinorder:
Thisistext.%comment
Thisismoretext.%anothercomment
Stillmoretext.
Thefirstnon-commentcharacterfollowingthefirstcommentistheletter‘ T ’onthesecondline;theleading
whitespaceonthatlineisconsumedaspartofthefirstcomment.Thismeansthatthereisnospacebetweenthe
firstandsecondsentences,sotheperiodandletter‘ T ’willbedirectlyadjacentinthetypesetdocument.
Notealsothatthoughthefirstnon-commentcharacterafterthesecondcommentistheletter‘ S ’,thereiswhites-
paceprecedingthecomment,sothetwosentencesareseparatedasexpected.
Agroupisanenclosureforacollectionoftextandcommandswhichenclosestheformattingcontextandconstrains
thescopeofanychangestothatcontextmadebycommandswithinthegroup.Groupscanbenestedhierarchically.
Theformattingcontextincludesthefontandthedefinitionofadditionalmacros(oroverridesofmacrosdefined
inoutergroups).Syntactically,groupsareenclosedinbraces:
{textinagroup}
Analternatesyntaxforagroupusingbrackets, [...] ,isusedbymacrosandenvironmentconstructorswhich
takeoptionalparameters;bracketsdonotnormallyholdsyntacticsignificance.Adegenerategroup,containing
onlyoneatomicbitofcontent,doesnotneedtohaveanexplicitgroup,unlessitisrequiredtoavoidambiguity.
SincePythontendstowardtheexplicit,groupsarealsomadeexplicitinthedocumentationmarkup.
GroupsareusedonlysparinglyinthePythondocumentation,exceptfortheiruseinmarkingparameterstomacros
andenvironments.
Amacroisusuallyasimpleconstructwhichisidentifiedbynameandcantakesomenumberofparameters.In
normalL A T E Xusage,oneofthesecanbeoptional.Themarkupisintroducedusingthebackslashcharacter(‘ \ ’),
andthenameisgivenbyalphabeticcharacters(nodigits,hyphens,orunderscores).Requiredparametersshould
bemarkedasagroup,andoptionalparametersshouldbemarkedusingthealternatesyntaxforagroup.
Forexample,amacrowhichtakesasingleparameterwouldappearlikethis:
\name{parameter}
Amacrowhichtakesanoptionalparameterwouldbetypedlikethiswhentheoptionalparameterisgiven:
\name[optional]
Ifbothoptionalandrequiredparametersaretoberequired,itlookslikethis:
\name[optional]{required}
Amacronamemaybefollowedbyaspaceornewline;aspacebetweenthemacronameandanyparameters
willbeconsumed,butthisusageisnotpracticedinthePythondocumentation.Suchaspaceisstillconsumed
iftherearenoparameterstothemacro,inwhichcaseinsertinganemptygroup( {} )orexplicitwordspace(‘ \
’)immediatelyafterthemacronamehelpstoavoidrunningtheexpansionofthemacrointothefollowingtext.
Macroswhichtakenoparametersbutwhichshouldnotbefollowedbyawordspacedonotneedspecialtreatment
ifthefollowingcharacterinthedocumentsourceifnotanamecharacter(suchaspunctuation).
Eachlineofthisexampleshowsanappropriatewaytowritetextwhichincludesamacrowhichtakesnoparame-
4.1Syntax
5

Plik z chomika:

Inne pliki z tego folderu:

Inne foldery tego chomika:

Zgłoś jeśli naruszono regulamin