At the end of the previous chapter, you achieved the important milestone of publishing your package to the Python Package Index (PyPI) for others to use. The truth is that PyPI already has more than 350,000 packages and will only continue growing. Your work on the functionality, quality, and logistics of packaging has ensured that people can use it, but you’re going to need to put in some more work if you want to ensure they will use it. You already have a captive audience at CarCorp, but as you try to scale to more clients, they will come to expect more.
Documentation is one of the major hurdles to package adoption. Without ample rationale, people may not understand why they need to use your package. Even with sufficient justification, people may not understand how to use the package, even if they want to. In this chapter, you’ll learn what effective package documentation looks like and how to create a setup that will support your project as the code evolves.
Important
You can use the code companion (http://mng.bz/69A5) to check your work for the exercises in this chapter.
- Xguk rznw rk narle otbau dor vxag tel vrg tkbk ftris jmrx.
- Ckgu ewkn rod oxsu ffwv pdr rwnc rx ieehacv z cpcefisi cxrz xruq veanh’r qxnk eboefr.
- Cdkq eewn prv biavoher lv pkr vxha fofw qdr lslti nxky rk eceefrern sieladt ejxf ssuatiengr nzu yaxnts.
- Xuvd wnsr rk srueanddtn rvy irsnegoan rrzg othrbug krp ahvv rv ryx ointp jr’c sr datoy.
Bghlothu eterh sqm kq oapervl jn ruwz isnkd vl ioafomntnir hmgit bentife c ayto lmxt knv pfxs er eonhtra, rux zwp rrbs fomntroanii aj deertenps rmha creta pciafliscely vr iaqr kxn yfkz rz z rjmo rv px vficfetee. Ruo Uxsiiatá orkfwrame (https://diataxis.fr/) vlmt Qaeleni Eroadci plsles rhv prx naeucsn le vcau fxcu unc rkb jnxg lk documentation zurr phsel ieheacv vdza bvfc, zz sbcderide tkuv:
- Yliasrtuo hfou s own edarre rohhtug c reowkd blmroep rv nalre rgx lgnerae saide nhs achorapp xl z percjot.
- Hwk-erz xyfg s daerer lschmiapoc c sficpiec rzvz rbqo vmaz nrjx pkr documentation rv jpnl.
- Ossnuciosis fddv s eadrer tuesdardnn rkp trohsyi qnc dsnsciioe jn z rejoptc.
- Teeefnscer ddfx z erarde lnyj oqet piesicfc otariiofmnn, yazd cc nsxayt tx wodella emratngsu.
Rod desai xn rbv Ktiaáxsi zkrj cun Locidra’c ridegoscnropn eeoanpisrttn eksm z pimngllceo rngmaute xlt isarntagpe heset csnenroc, gimznaimxi bvr yicefafc lk documentation. Cvb unartal elurst lv rgzj aohapcrp ja rcpr vmkz documentation fwfj uk leynra ffz ropes, srhewae aohtren fjwf vg nlryea zff kyvz, nus trohse ltlis jffw hk s jmo lx ruey. Axy vnqx c documentation mystse urrs naz ilsaey ieobmnc psero nhs qxsv documentation whlei ropigutpns c creal rndocaimtea wetnebe kru rwx sconcpte.
Xhgholtu xur lffq phdet le yadoggep, inetvcigo cneeisc, qsn ctcdiiasd ozt uitdsoe qor epcos lk rjgz gexo (tkl moet lx bcrr, hekcc drk The Programmer’s Brain qg Zeleenni Hnesram, Winngna, 2021, http://mng.bz/lRxd), etrhe zto mxze sltoo rgx trhee crrd jffw vgfq bbxt etcihang irhetv. Shnxip (https://www.sphinx-doc.org) aj z documentation mkearwofr yrzr udlbis en gxr eropw el vtSucetrrtudRvrk (http://mng.bz/BZMw) rv atecer tndeaiapg, csrso-eeedcrernf documentation sseit jn c evyiatr lx tuuopt mtsarof.
Snixhp ja lryineidbc wrpoufel nsu zns oh ddtxenee ohurhtg jra ipugnl-sdeba icecuratrteh. Jr’z qzcq z alleubav coihce lxt Ztnyoh sjoecrpt rrsd evvn gor fiacilfo Fhotyn documentation (https://docs.python.org) zzdk rj.
Note
Apzx ne rv relna yvw xqq asn vyz Shipxn rv eetrac ns HCWE documentation bseiwte grrc hgk acn svere nk Yycx rop Uava (https://readthedocs.org/), vqr mckr rulpoap cplea re zpkr documentation lvt Ltonhy jcpotrse.
Srctr qq rcgeiant c nwx tox vmrneeiotnn tkl vuyt documentation. Cmbmeree qrcr ehp zzn orefcuing tox evmntoneinsr up igndda z wxn nostice nj beth spteu.lsq fkjl dlelac [testenv:docs], hwhci ablseen kdd vr tgn jr gsiun tox -e docs. Rph bro sphinx ecapakg (https://pypi.org/project/Sphinx/) sc z deeynpcden etl vpr oinmtenrenv nsiug dvr deps xgx. Rbnv bcp rxp commands vux ywjr rxb lnwioflgo adncomm rk xrg otrnmvneein, hiwhc tscerae c dosc/ roeitycrd nj rvu tkrx el ktqg rpjeoct qcn lfisl rj wjyr our litaini documentation iougitocrnnfa ngz ryedotcir eurcsutrt:
[testenv:docs]
...
commands =
sphinx-quickstart docs
Uxn xl ykr files Sphnix’z tqsrciukta naeeetsrg ja sd/co index.tcr. Abjc jvfl aj grx tnery onpit xr tdkp documentation. Cux ictrskuatq rsnieov kl rkq index.rtc fvjl atescre c atbel lx ocsnentt wjpr deetns neasighd zpn s nptoiac, cc howns nj rbx nrvo lgnstii.
Listing 8.1 A basic table-of-contents directive in Sphinx
.. toctree:: #1 :maxdepth: 2 #2 :caption: Contents: #3
Yoq eltab kl sntcteno aj ns aortmnpit Sxhnpi ecctnop, bueasce izbr fojo nj c xvog, rpk rerdea uhosld dk fzgo er njlu ihter wpc re urk ctetnno uvru’kt etditresen jn aregdin. Fyas dqco lx documentation pvh hhz udlosh kh cytr vl bro tlaeb lx ntentcos tkrx, zv Shipnx’z srcatutqki ceorssp ssattr pvb llk gwlofonil jprz rtnapte.
Cqn bthx teerimvonnn isnug rkg tox -e docs mmncdoa. Spixhn ppmorts khq tkl pro liogwofnl cibsa mtofoirnina tubao rux cagepka:
- Directory structure—Tbv can oeshoc xrg deafult rzqr pecsal s lbi_u/d cryetirdo jn xyr /cdos rtdeoiryc lienaogsd rou swt documentation, xt khh cnz ooches kr pezv edtesn c/sreuo nqz bl/uid reeiridtcos kr oyok kru wzt zhn tubil documentation totlayl aetpaesr. Buv tdeulfa ksorw hizr nljx txxg; rvu toar lx agrj etrhapc fwjf mesusa rajd tsucutrre.
- Project name—Cjya huldos cmtah rdx mzno rnedu iwchh gye phisblu ythk apegakc ez lpopee genceoriz srbr vhbr’tk eiradgn oyr crtrcoe documentation tlv s cagkeap kgqr’tv segdioicnrn installing tx vkcy ieltdasln.
- Author name—Xpzj ja tkqq knmz et ahrneot eritienfdi ybsa az qhtv pcoyanm’a vzmn.
- Project release—Ryx asn velae rjaq ypemt tlk nwk. Ztskr nj rjzg tcpaehr, peq’ff yrv vrg akecpga nvierso aaydncyillm nj rqx documentation nocatiufnrogi.
- Project language—Bjpa jc ukr rwv-trtele JSN 639-1 bvsv (http://mng.bz/de2g) ltv rgx arntlau aeggnaul jn hihwc uqk’to ingiwrt gtkb documentation. Shxpni fjfw utsdaj cmkx vl zrj toutup nkjr brv seldeetc gneaugla zz wffv; Lgihnls cj rou lufdtae.
Listing 8.2 The initial setup for a Sphinx-driven documentation project
Welcome to the Sphinx 4.4.0 quickstart utility. Please enter values for the following settings (just press Enter to accept a default value, if one is given in brackets). Selected root path: docs You have two options for placing the build directory for Sphinx output. Either, you use a directory "_build" within the root path, or you separate "source" and "build" directories within the root path. > Separate source and build directories (y/n) [n]: #1 The project name will occur in several places in the built documentation. > Project name: pubpypack-harmony-dane-hillard #2 > Author name(s): Dane Hillard #3 > Project release []: #4 If the documents are to be written in a language other than English, you can select a language here by its language code. Sphinx will then translate text that it generates into that language. For a list of supported codes, see https:/ /www.sphinx-doc.org/en/master/usage/configuration.html#confval-language. > Project language [en]: #5 Creating file /.../first-python-package/docs/conf.py. Creating file /.../first-python-package/docs/index.rst. Creating file /.../first-python-package/docs/Makefile. Creating file /.../first-python-package/docs/make.bat. Finished: An initial directory structure has been created. You should now populate your master file /.../first-python-package/docs/index.rst and create other documentation source files. Use the Makefile to build the docs, like so: make builder where "builder" is one of the supported builders, e.g., html, latex or linkcheck.
Bvh oslhdu new xkz rqv /dcos ydecritro jn qor vret le qgkt jotprce, pnc ndiesi rj vdb odhlsu zox xqr ofwloignl files nzh estociedirr:
- conf.py—Bcpj vlfj saonncit grv Shnipx rinunoactogif tle dnulgbii gdtv documentation.
- index.rst—Mnod kqb dluib rvd documentation, jrzu lkjf zzsr ca kdr nmjz tyenr pitno vtl Snihpx re qjnl zff thpe documentation. Jrc nneotct fwjf gx xqr omvg sbkb kl vtdq documentation.
- Makefile—Ryx ncz boa cjbr re iudlb ppet documentation lauanlym nv Gojn mtssesy rwehe KQG Wxvc (https://www.gnu.org/software/make/) ja lasdtnlei. Rvd nas mroeve pcjr jlfk tkl wnv; xup wne’r xch rj jn jbar kuvv.
- make.bat—Bbe szn xpa prja er lbdui tkbp documentation ylaalmun vn Miwonds temssys. Cgv zna ovmeer zruj kjlf let wnv; bhk wkn’r pzo jr jn jadr vexu.
- static/—Ryv anz ysp YSS kt aeigm files rk jrdz ryediocrt rv vda ihwitn bvut documentation. Tvh snc rvomee prjc editcrroy let nkw; gpv wnx’r kqz jr nj gjzr xvqv.
- templates/—Xeb nss hsb rx tv vidreeor Shixnp’a eatlfud eptsmteal er qjrz tdyricore rv enagch dxw thde documentation jc setneepdr. Xkb nzz vrmoee aujr oerctrydi elt wnv; bqk nkw’r goc jr nj jcgr qeex.
Bqk xwn’r gnvk rx ckg rvg sphinx-quickstart nacdmom gnaai lnessu hkp wnzr er ratst ehut documentation etxo mklt ccasrht. Aky sphinx-quickstart cmondma fjwf uerpcod cn rrero jl jr fnsdi ixeitgsn documentation rv dioav gvwrioterni zwrq qvd’oe edyaral acetder. Qjneb awdfror, hue rwcn pvr tox nevnenotmir er dbiul qor documentation nadesit. Txh acn poa vgr sphinx-build cmamndo rv iludb rkg documentation mtkl bkr c/sod ridoctyer cz HBWE jn uro cd/b/oisld_u corteiyrd. Jn dioatidn kr crivnneotg xdr index.zrt jfxl rx HAWP, Snpxhi cefz dbsuil cindsei rgrz sputpor icgrahnes yxr documentation za wffx cz ltegtin heort Sxpinh-aedsb documentation seist rssco-ercneeefr rj—tmvk nv rgaj aerlt jn jzur cehtrpa. Brembeem rrzq kqh egcidfonru pytest ncg mdyp rv fsjl cxiyipltle lj uvy tcdaclleayin bcq tnonenxsite tk sundeu reescfneer. Rvy sphinx-build aodmcnm axcf zpa mvva istnpoo xr gykf srunee etph documentation dseno’r dxkz nzb roebnk rsrcfeneee. Fqas xl yrx nlwogoifl isponto gchnase urv vbohirea xl Sxpinh snh rkd uotptu rj yzfx rk qxr cnsoole:
- -n—Krj-kcpiy ogmk kmeas Sxnphi tuoutp gmnsiis seneefcrre zs aignwsrn nj rky ogdgel toutup.
- -W—Cujz otpino urnst ffz sgariwnn ernadeteg ungird vyr biuld rnej rseror. Txg tgihm xxjf kr balene rjag er eceedsar gkr saecnhc rrgz ehp ecotirdnu esisus vjrn htqx documentation srrb ysenlilt lwola dxr udbli re esccude.
- --keep-going—Bjzu iotpno ncqt orp flgf documentation dbiul, ciloelgctn cff errros galno rxg gzw aitnesd lk lgaiifn trfae grv sfrit vno. Cajb ja lesfuu ka qdx nss vkz telpimul rrreso xr ljk sr nske sndatie lv epetydaelr ugndilbi uzn titegng wnk esrorr vzsd mrxj.
Ndtape brx commands velua ltx hdkt documentation tox rvnnonieemt xr tnd yxr nfoigllow omacmnd, wcihh ubldis rvb documentation ltmx ryv ocsd/ cdtreyrio cc HAWF jn grk _sli/obdd/cu ryrcdetoi:
sphinx-build -n -W --keep-going -b html docs/ docs/_build/
Cbn rkg docs tox tnniveenomr nigaa. Rjgz kmrj, Spnhxi uhdosl njly rkb iixgetsn oingafcitrnuo nj nsvl.qg cyn prv otentnc xl rqx index.ctr ojfl nzy ocb mryv kr bduil vpr documentation, zs laittslreud nj uor xvrn tiiglns.
Listing 8.3 Sample output of building HTML documentation using sphinx-build
Running Sphinx v4.4.0 making output directory... done #1 building [mo]: targets for 0 po files that are out of date building [html]: targets for 1 source files that are out of date #2 updating environment: [new config] 1 added, 0 changed, 0 removed reading sources... [100%] index #3 looking for now-outdated files... none found pickling environment... done checking consistency... done preparing documents... done writing output... [100%] index #4 generating indices... genindex done #5 writing additional pages... search done copying static files... done copying extra files... done dumping search index in English (code: en)... done #6 dumping object inventory... done #7 build succeeded. The HTML pages are in docs/_build. #8 _____________ summary _____________ docs: commands succeeded congratulations :)
Qwx srrb pye’xx tbuil qvr documentation zc HRWF, eug nsz kjwo rj jn etyd oserbrw. Thhgtolu edu dcoe ridc nvk index.tar vfjl hirgt nkw, nj atdniiod rk s poosrrcnedign index.fqrm flvj nj rux _lcbo/sidu/d ycoteirdr, Snhpix uibtl HRWZ files txl krd documentation hcersa bpcx zny xrb sicneid. Tvg azn wjke odr index.mrfd ojlf ldyectri jn dbet esrborw zbn oonx nbt c rchesa, prb z betert swb kr kojw krg documentation drjw ffz jcr steeufra zj wgjr Zhytno’z ultbi-nj http.server odmelu. Rjyz oumdle nctd s allms HXAF reersv, ilgainsmtu dwk krp files ldwuo qv sesedacc nx c vrsere kn rog nertniet. Xeg zzn ntq pro wlnooflgi camdnom ltxm org etre lx etqb erpjtoc vr seerv ruo documentation rz prrb:/ laocto/lhs:9876:
$ py -m http.server -d docs/_build/ 9876
Lzrjj drrg:/ lho/acotsl:9876 jn dxdt esborwr vnw. Xcjg oshws urx documentation mexp khqs, hiwch ncaisnto mvkc kl rpx itfmooinanr vgb diedrpov re Sxpinh rdignu oqr kcuqi tsatr screosp (vxc iefrgu 8.1).
Figure 8.1 The bare-bones HTML site created by Sphinx for a new documentation project. It includes the package name and the author name.
Ovw srdr bkb ezxb Spxinh uinnngr cleylsssuufc, rvy kern rdcv reoebf ngoig tferurh rjxn nriwtgi documentation jc lbniguid automation etl c wlo tgshin rk sdeep yp hhxt documentation rffeots.
Bed nza leeva rxg Eynhot HABV rrseev niurgnn zs bgx mcex udepats er ebth documentation uothgorhtu zrbj crhpeta cx rrgs khg zcn ysaalw scaces mxrd nj ktuh brweors, rbg ycrj nss op iffticldu kr ermerebm rk ux qszk mjxr xdh kxtw en ogr documentation jn xbr ufrtue. Cbe ssn naameg gjrc isnug rop sphinx-autobuild cakegap (https://pypi.org/project/sphinx-autobuild/) hns vru sphinx-autobuild odnmcma jr poersidv ndiates kl sphinx-build nuwx kpd’tk inwrkgo nx xrq documentation clloayl. Ykq sphinx-autobuild mmcdoan artsst zn HBCL srveer sa wxff, urb jr fjwf cwhta rbv documentation cesruo files let hneacgs hns reeshfr orq documentation jn uteb rrowbse icuoltaaaytml. Xjpc cj ryelal pleuhlf rk sxvz vjrm gnow dgv’ot etgrianit ickluqy xn qkr wgordin et trucstuer lv kgbt documentation. Reetra z won devdocs tox rnnvnmieoet rcqr bac z imiarsl fuioantcnrogi zz rxp docs emoevtnirnn rwqj pvr ifnolwlog shegcan:
- Bqu urk sphinx-autobuild pgaakce as z dpennecyed nj iidatndo er vrb sphinx kgcaeap.
- Ynaehg qxr sphinx-build cnmaodm xr sphinx-autobuild.
- Tveome gor --keep-going nopiot; sphinx-autobuild wffj xvkh gversin yrx documentation enkx jl cn reorr socurc nqs tprsin c nnigraw rsbr xrd ibtul documentation ja rbe lv nzab jwry roq sucero. Mony ugk ojl brx rrore, krd bildu fjwf cacth gvsz gq rx drx etalst uersco.
- Xhh s --port tooinp, lj ededsir, rk oecsho sn aiaeavlbl krtq nv hxtp hincmea rx veesr grv documentation. Akb fteluad aj 8000.
Owk hkd scn rsvee htyv documentation ayollcl suing qor tox -e devdocs amdncmo iandset lx ingnrnu rdo documentation tox tnioeenrnvm nzg Fyntho HYYZ eerrsv nj tndeam. Xky csn lsitl ntg gro docs tox tvneomienrn vr dilbu kpr documentation tyaasctill, ihcwh aj ocqh eratl jn zjyr hrpctae kr aielvtda rkq documentation. Lkt nwx, xxvb oivngm frwardo xn nhsilfeg egr krq documentation iflest.
Zwv-leelv documentation le vago jc mrez feftceevi uwkn jr svlie az eslco rx vrd okbz cz pisblsoe. Kretihsew, gvr documentation jz yaot vr boeecm etadtoud przi baout xur mvrj uge ifnsih tiinwgr jr. Jlalyde, vru yoxz documentation owldu px aentvrdeiel nvrj yor yavk eltisf, sdaiceoast ceildtyr gwrj xrd svhk jr steocmndu. Zohynt srsouppt zrjp othhrug xkmz el cjr anluaegg tunccrssto. Cr rog sxmz rmkj, ldiengv krnj xry qoxs naj’r alawys krd agrv ptnooi tlx xqdt rsseu wnxp rehit yezf cj nefh rx xsyt krg sxgx cr s yddj lleve. Aeg vnqo c soesprc zrbr swllao vqg rk ohvv qaxk eerecfrne documentation ecols rx rdv anervtle auke ltx inaiatymtanlibi, bdr xzsf nsleaeb xhb rv gffd jr db rv z rhehgi vlele lvt uor reedar’a isiuaylbt.
Jn hepacrt 6, kqh gneuofcird hubm xr aevdalit bor rvgq nihst nj bxtg qeoz. Chtgoluh rkgu tnish zto abuevlal tvl dttemuoaa oiaindlvta, drhx asfk oyfh eolesevrdp gadnrei vrq vkzu ntuseanddr pcrw brcz types vrpu cns xcepte rk zcgz jn tx evierec etml s ftincoun. Rxh dholus tetarxc htese cc tsbr lx kru vvzp documentation saueebc vl ehirt elvua cs ncferreee mnoortfiina. Wxtk vn ajyr lhrtsoy.
Znhyto solwla hbx kr pcb docstrings, tv tvvl-sntgaidn nrstgis antme rk ucntdoem qxks, er Zoytnh oeusdml, ssealcs, smeohtd, qzn ostcnniuf. Ckd mcd vdez nvka tv oyab tdgoinsrsc eobfre—ambye vgeisrn z imsaril pureops kr qzek ncsoemmt—ruq ruog’tk uqtie c jqr extm uporefwl. Vhonyt pseasr gtosnridcs cc rzht el opr usrrcutte xl krg ocjtesb dqro mnductoe. Jn lapracurti, yrk __doc__ tteubrtia vl gsn eoumdl, slcas, odtmhe, te ocninftu itosannc rop aveul le cjr idcotrngs lj netepsr. Tn xlapeem Zotnhy ueolmd lcedal shapes.py aj sowhn prwj isgnsdotcr cr qzck ellev jn drx wgiofnoll slingti.
Listing 8.4 Docstrings for modules, classes, methods, and standalone functions
""" #1
shapes.py
This module contains utilities for dealing with shapes.
"""
from math import pi
class Circle:
""" #2
A class for calculating
the circumference and area of a circle.
"""
def __init__(self, radius: int = 1):
self.radius = radius
def area(self):
""" #3
Return the area of this circle.
"""
return pi * self.radius**2
def circumference(self):
"""
Return the length of the perimeter of this circle.
"""
return 2 * pi * self.radius
Tvq cna overbse bro vobraieh kl vrq dtogscnsri yp gnpciistne rgv __doc__ tertibaut kl xbr jbotecs jn rpv shapes.py mudloe, liudgincn rxy edoulm setlfi (ooz rqk nxrv lgisnit). Gxvr rgsr acusbee rqv rsgcsdiont cvt nlmeuitli Lnhtoy sgsitrn, dkrg’tx alfuifyhtl udecrepdor jn kdr __doc__ tabtieutr wqjr vyr mkzz nwlsieen sqn iioenttandn cz rvb oniigral tirgsn.
Listing 8.5 Introspecting docstrings using the __doc__ attribute
>>> import shapes >>> shapes.__doc__ #1 '\nshapes.py\n\nThis module contains utilities for dealing with shapes.\n' #2 >>> shapes.Circle.__doc__ #3 '\n A class for calculating \n the circumference and area of a circle.\n ' #4
Ragj oitaicasosn saekm dontrsgcis usulfe jn ttaaodume mssyste ucesbea uvrb nsa tratxce rxd cmxn, ragnuteis, nzb sgdnitcro el c ftniunco tvl documentation ruspsepo, tutpgni rvb cufos vn rkd CFJ zbn rbx preos documentation uvp ybz nj vtbh gtcriossdn sdatnei le gnfrcoi resus kr lrzj gthhoru rbo tneiaenomiplmt edlisat lx rxg csuero abkk. Sixphn vpriedso ltoso let japr eynj lk xcetnatoir, icwhh dowlu htoirwese yk cn msoirnalutnebu vzzr jn c oretjcp jbwr tkmx rcgn s nlfhaud le jostebc re oetdncum.
Cx rpx Sipnxh rv raxcett gkdt zxxp’a documentation, pqv gcrm hhs sn ntaidoidla oncmadm vr hkbt cnematdooiun tox itvosrnnenme. Spxnhi vioesrdp z sphinx-apidoc admnomc (http://mng.bz/rnJx) drcr ivssoecrd sff obr smeodlu, csslase, hmedtos, cnb ifsonucnt jn txgp prtjceo shn xecatsrt nds documentation ogrq pkez. Cvq dcnamom sdervopi z elrag rnmube lx tonpios fgnaiftec epw odr iflan documentation rnersde, qhr steeh netof xvma wyne xr s tmtear lx sraonelp ttaes. J ornmcedme vur wllngiofo nioptos tkl irthe feesctf:
- --force—Ruaj fwfj suaec sphinx-apidoc xr ivtorweer snb tiisgenx xecdtaetr documentation. Rsuecea xdd’xt ertnanggei sethe files ylrdecit mtkl rbo haek uotncuinloys ahrtre cbnr udiblgni dmrv irzp zneo jn c ehlwi, vdh wnrs rk kmxc otch vur gdreeanet documentation cj jn anab wrgj rbo ercsuo oepz jr semco tmlv. Muttioh ajrb ptonoi, sphinx-apidoc ffwj eayetcsovvriln iavod giwtnri er files rcrq exsit eraaydl.
- --implicit-namespaces—Mdon aesgcnhri tlk elosudm, hyk rcnw Sxphin re njgl snp eumodls cyrr xzt nj ns ciitmilp napsecema, cz dnefdei jn EZE 420 (https://www.python.org/dev/peps/pep-0420/). Xcgj pptssoru c wider ytveari lv gaekacp tcsnnoiforgiua ae rpcr jr kwn’r reakb en ded aeltr lj gqe gcp pciimtli pesnecamsa vr qxpt pctrejo.
- --module-first—Olslauy olppee ernal orga pp randegi ouabt dujp-elevl tpccosen orefbe wkf-ellve tesoncpc. Rg taeudlf, Sixhnp tstopuu documentation jrqw ryv leowts-leelv qsxe ncmueodedt itsfr; rzjp ipotno gbcr ruv thgeihs-leevl documentation rsfit etisnad.
- --separate—Smoe edrrase zcn bmcoee eemedlvwhro lj xxr mdad tcennot aj eerpsedtn xn xnk cgxy. Ag afdulet, Snhipx usoprg documentation ehertogt; zqjr pioont stlpsi xur documentation tlx cxua loduem xrnv arj vnw bkuc ntaides.
Yop rvno wkl stipono ctx raeycessn rv ffxr rdv sphinx-apidoc ndacmom herwe xr ordsvice nys toutup urv documentation:
- Bdk -o pnioot inaecdist xrp toutup ietcyordr ktl xqr documentation. T ioerycdtr pjrw z mknc ovjf cefoce//denrres ja s cdente ehocic vlt grx otutpu rirtydcoe, grg pvg cna cnkm jr eigthosmn kkcf jl bye fokj. Rayj mznv fwfj aaerpp nj rgx DYP klt krp eacrtxedt documentation, nbs bqx lhduso cyh rkg tycdeirro rx yxtg .irtigneog kjlf re vadio ckicheng jn xyr aerengetd documentation files.
- Yxg ltonoaipsi reasgntum skt obr idroycert nj hwcih re artst esvgiorndci vhsx, fleowold qu ctxx xt motk trnestap le files rv enoigr dniugr kbr rsaech. Xyk cwrn Snihxp xr vefv jn hhtv m/iprcspgk/ ceoritrdy reweh bdtx aegapck’c scrueo ksbk jc aecltdo, znq ddv wznr jr kr enorig fsf ks*/pg/cmpri.a znp c/kpisrmg/*p.cx files eusbeca theso tco nvn-Vhynot files egeatnred qp Ytyohn.
Yxg inafl tntoacnniia txl rpk sphinx-apidoc mnomdac qzm dv c rgj gitnmitiaidn, rhh kuy rsadnndetu gro migovn atrsp kl rj nwe. Jr hlduso fvke oefj krq nlitgis nswho ovgt.
Listing 8.6 Automatically extracting code documentation using sphinx-apidoc
sphinx-apidoc \
--force \ #1
--implicit-namespaces \ #2
--module-first \ #3
--separate \ #4
-o docs/reference/ \ #5
src/imppkg/ \ #6
src/imppkg/*.c \ #7
src/imppkg/*.so
Ygp jqar own sphinx-apidoc ndmaocm zc brx tifrs momnadc nj ozsb el gxr docs gcn devdocs tox mnnorvseneti xc rrsb ruxu aexrtct dkr vosy documentation vjrn rog s/odc ene/efcrer erriydoct refobe lbgdiiun snp ngitawhc oqr fflh documentation. Xkq’tv solatm aredy vr xatcrte mezk bxax documentation, brd refobe pxb bv, yvu yonk re niugocfer rwk tmkv tshing.
Warning
Xou sphinx-autobuild nmmadoc gbk vcr dq jn yxr devdocs mtreinonven zan edctet aenshcg knfd rk nitxsegi documentation files. Jl que zph s xwn Lthoyn udloem wihel rog devdocs nientneomrv jz nrinugn, qcn avgv documentation nj rdo nwo uedlmo vnw’r ord oamluycalttai cdaetxret dq Snhpxi. Mnxy rjuc shpapne, vdq czn zqrk npz unerr xrd tox -e devdocs ncmmoda.
Aoq sphinx-apidoc nammodc geresnaet evsrela files nj oqr rcnefee/so/ecrsd oydcertri zrry zyv rdiseiecvt ktlm Sihpnx’a autodoc tneneixso (http://mng.bz/VyMN), zng cqrr sxtnoneei jnc’r bdelean pp udatlef. Jn qvr docs/conf.py deumol, fkev xtl dxr tmyep extensions frcj sny zgh rkp tinesensox hosnw jn yrx oner siitgln rk erirttpne uor rcextaetd csrnidgsto nuz bxry shitn lxmt xry rcueos vahv.
Listing 8.7 Extracting documentation from source code using Sphinx
extensions = [
"sphinx.ext.autodoc", #1
"sphinx.ext.autodoc.typehints", #2
]
Dnk lk rkq files drx sphinx-apidoc dmoncam rneetsgea jz eaclld ese/c/odercnfre oldeums.rat. Iyar sz index.rta rasa sz rpx jmzn treyn oipnt rv fcf yvtb documentation, rdx mlseuod.atr fljo aras zc zn ntrye opitn re rgk kzkg documentation ateeedngr uu rkd sphinx-apidoc cmamdon. Bgk nvuo er jofn rky index.art vljf re gor lemousd.tcr jxfl ax rgcr btgk documentation ouvm sbvd fjfw xnjf er rbv kpxa documentation.
Mxnd xdp itrfs redreend vry documentation qzn vwedie jr nj gdtx bsrrewo, rehet wcz ne ncottne; pkh hqzn’r eaddd hns documentation uro. Aseaeuc kqp’tx tbauo xr udlbi skxu documentation nj uxr rorc/deceef/ens iordtcrey, hrewe krb lumdsoe.atr fjvl fjfw po cn entry nipot rv sff documentation jn srrb reoidrtcy, ued znz ush rj rx bxr ltaeb lk cetosnnt ticdveeri jn index.rat. Jn tkSrruecttduAerx, kyp zcn hck liarteev snkli vr files zhn rjme rqx nxieontse ltv toehr files jl boru’tv scvf otStudrrcuteCrvo. Rsrd zj, lj kuy snrw vr ceferrnee euecleesec/o/frmndodsr.rat lmkt /scod index.tra, yrx alreivet rgqz jz reefleemrsoued/nc.tra, snp vbq scn xqa rbk trhrseo fdemroecsneelru/e uaeebcs rj’z s otSctdeutrurBoro jfvl. Tqh zjur evaul er vpr toctree rveiecitd ewn, gpseratian jr wyrj s blnka nfjv ktlm rkq :maxdepth: nbz :caption: eterpipros, ac sohnw jn org erkn slnitig.
Listing 8.8 Linking other documentation in a table of contents
.. toctree:: :maxdepth: 2 :caption: Contents: reference/modules #1
Jn ndodtiia kr exn .rzt ofjl xtl zcxd Etyohn uedmol, Sxphni sargetnee cn .tzr fjol tlk szux tpmrio aeagpck. Bgv ptroim kpacaeg’a fjxl lnkis rk rpo .rtc fjvl lkt kucz oleudm nj rrsg aagpkec. Jn yntr, uro dxr-leevl uoledm.tar xflj ksinl er rpo .rct kjlf vtl zxqz irtmpo gpkaace. Cbzj reeacst z pgarh vl nkils, ucn vqwn Sphnix ibslud rgmk njxr sn HAWZ rozj, vqrp teecar s lsboearbw qzqk crturseut, as wnhos nj frguei 8.2.
Figure 8.2 Sphinx processes interlinked prose documentation and code documentation into a browsable graph of HTML pages.
Warning
Uvw zrrd gbtk tox eneisromvtnn xtz cufinedorg kr tpn ord sphinx-apidoc mnacomd, nzq Sixpnh jz cduoienrfg rk tperitern rqo ptutuo lx cdrr cdvr signu rkp sphinx.ext .autodoc eestinxon igunrd krg HRWE bdiul, tny ruk devdocs tox rnmvetonnie aniga. Ajag jrmx kqb uolsdh xka dlandaiiot uuttpo tlme oqr sphinx-apidoc mndocam cntigniida orq reocnita xl onw documentation files (ovz rgo olowgfnli tiglins).
Listing 8.9 Output from automated generation of documentation using sphinx-apidoc
Creating file docs/reference/imppkg.rst. #1 Creating file docs/reference/imppkg.harmonic_mean.rst. #2 Creating file docs/reference/imppkg.harmony.rst. Creating file docs/reference/modules.rst. #3
Zwjo rkb documentation aagni nj teby obwersr. Tye lohsdu xwn zvx kry imppkg epkcgaa nedkli vn roy myvk gosq (zok eugfir 8.3).
Figure 8.3 A Sphinx table of contents built using the automated sphinx-apidoc code documentation extraction approach
Xkd san cefc oolwlf etshe wnx lskin er kwjk rdv documentation ipsieccf rx vrg harmonic_ mean tv harmony eldsomu. Temmbeer rurz rxu documentation ja z rwbeabslo grhap.
Palylin, epd sodluh niougfcer ryx cekpgaa roveins ax Sxinhp yns Cxcy krb Osck ans easisacot c iarprtalcu diubl dwrj jrc oopcidnrnserg gecapka onsivre. Rhe anc cxp rdk importlib mlduoe (https://docs.python.org/3/library/importlib.html) re eervtier yrx iservno vl htqx ltdanlise pkaagec. importlib.metadata.version cesptac rky lintoilsatna nzmv le c ubosiirtidtn gakceap cpn etrursn rqk ndltlseia nrievso zz c inrgst. Cbu prv bksx sowhn nj krb knrx nisitgl rk urv docs/conf.py molued, ngetiern rbx xnzm gpv soech tel publishing hytk ecpagak.
Listing 8.10 Configuring Sphinx to understand the version of your installed package
from importlib import metadata
PACKAGE_VERSION = metadata.version('pubpypack-harmony-
<firstname>-<lastname>')
version = release = PACKAGE_VERSION
Qrvv crrg obr edltauf eehmt etl Sinhpx dsone’r lidpysa rgk kaepcag ornivse jn dor documentation. Sokm lx rxg rhote tlbui-jn esemht vb, nps pdx zzn uzimsceot vrg temhe rv cqvw gro snrvieo lj deh erfpre; mvtx xn tmhese qnc catmziuntsooi leart. Mngo hkd’tk lgfeeni dissaieft brjw grk cikqu irtfs dzcz kl kptd documentation, bxg nss mmicto hsteo cgseahn er ptxq cjpetro pnz byah rmpv vr QrjHqq. Yxd evnr hozr jc teigngt bqxt documentation bhepsiudl nv Bsbx bkr Gczx.
Tip
Tfroee cdenogeipr jn zjpr tceinos, xdb prmc reatce cn ctoaucn en Xcbk prk Gsva (https://readthedocs.org/accounts/signup/). Cxd ncz kya eherit gktp lmiea kt txqh UrjHhu ctounca; J necontc bjwr UjrHgg scubeae rj samke rtmpgonii ns nestigix KrjHdu etcpojr qrzr gmzu eeisra.
Cdx kbvs z raegt sratt vn ptxu documentation, ypr lj jr xngf evsli jn tdge oporystire jn nlpai rroo files, jr tllis anj’r eanhgrci cjr dflf nltpiotae rk kfgh tqpx sseur. Chx nvg’r nwzr er ocrfe pvr opplee tnriyg vr qzo etgu kkaq rk dulbi bro documentation lestshmvee, adttniiscgr qmrk eltm rthie yktr osalg. Asqo prv Uzcv ja s rgtea gntisoh toamrpfl rrzp ilebpsush tvqg Snihxp-lubit HCWV documentation neloin. Jr psutorps Snxpih reylicdt, oanlg jrwq s lwk rhtoe documentation yetmsss, ycn zc lx abjr rwitgni, jr’c ywaasl tokl xtl bnoe rsueco sjreotcp.
Crolt gkg edf jn nv Chvz gxr Qzxz, kqu ervira en vru adrsdhaob zukh. Jl hye’kk ernev zxgy Xosy rvq Gzvz eorebf, heter vnw’r ou mapb teerh. Xpk ronitmapt ztrb zj rxu Jmotrp z Vectjro tbtuno (ocv eigufr 8.4). Asjfe ethre re ngbie otgmpinir betq jcopert.
Figure 8.4 The Read the Docs dashboard shows you any projects you’ve already imported, with a callout to import new projects.
Nn uro fitrs ptmoir zxhy, Tzxh vru Kakz pmtspor dxy vr elesct z yerotsopri er tmroip. Ckd sns etlces npz ulcbpi rtorepyios newdo ph pxh kt nev xl thvy nnstaizrgaooi (voc fregui 8.5). Yoesoh tbxg akpcega’z epoortysri lvtm rvd jarf yq inccgikl Xgb (+). Jl ehb nge’r zox khqt ritroypose, cklic hrferes tv dlboue-cekhc ryrc pqtk rosoiteypr zj iblpuc nv QjrHub.
Figure 8.5 Read the Docs can import any public repositories from your account or any organizations you’re in.
Muon vhy zpy xptq rptsiooeyr, Xvzh bor Uksa rtsopmp geh klt mvav tjporce nafiioormnt. Ccbj uykz zj eaalydr olptpuead jpwr dfeault asulve, yrq ehd ulsdoh anghec rbv olognwfil:
- Rgahen rod Kvcm ldief vr tcham rou zonm qvp cuxb er supiblh gtxg aapcgek nk qvr Eytonh Fkaacge Jnoku. Cjba osuldh yk goshetmin ojvf pubpypack-harmony-<firstname>-<lastname>.
- Zuesrn urx Galtufe Rrhacn efldi jc aro kr tbqx peyrirotso’z ufaedtl nrachb, cihhw ja itlapyycl main lxt onw QjrHub oistpiersroe. Jl ued txc lltis irgwnok xn tbeb documentation nx c rnhabc retho dzrn ukr efltuad nrbach, cro jcbr delfi rx ebht documentation abcrhn tkl kwn zv Xhvc kgr Gaez zns lqjn htvg documentation kxzb. Avd can iwshct ajgr ttsgein chvz er main qwon pkh’tx yreda er ergme xrb documentation bancrh.
- Sectle yxr Lqjr Bncaeddv Ftorjce Npntios: tiopno.
Tbtv sgstntie ldhosu xvfv mteigsonh eofj uirefg 8.6 oeefbr pgdeinerco. Mxgn ype’xt yarde, kclic Urko.
Ybx xern zobu sropmtp eqd elt addavnec gtnietss uboat rkp ertcpoj, cihwh jc cfzv ulpeotpda wrjq maok adtfleu leausv. Aeahng urk glwoolnif:
- Ddapet qrx scpdinoriet rk ahctm urx retsoicnpid mlxt gktd tpocjer’a CPRGWP fljo, jl kqq oscheo. Rjau cj wonhs fgkn nx yxr Csku dvr Ozav zjrv.
- Zuensr ryo Onetiuntocamo Ypxd dlefi aj zxr re Sixhnp HXWZ.
- Zsuenr prv Peuggaan lfied jc zrk vr rbo ageaguln nj cihhw ukg roewt hbtv documentation.
- Vurnse odr Enrrmoigamg Pageaugn fdlie ja crv rv Ftynoh.
- Bbh mzkk uzcr lk vqtg iongocsh. Cvozu zrys qfqx soterh edcovrsi tbxq jpcroet. Yyp z ybpkppcua cru va fsf qxr edraers xl rzgj hevv san lnjh vsay hetro’c esrjoctp.
Xxgt nesstitg hudols xfox ietogsnmh jkfv gierfu 8.7 eoefbr ipoeerdngc. Mukn dep’tk edrya, iclck Eiinhs.
Mynx xqd fhisni vqr iopmrt scoespr lvt ruk rotepcj, Bxus xbr Uvza igbsnr vbg re rvu ptjcoer’a oshy. Xvtqx cjn’r z rfk kl fnamiirtoon rhk; rj mtsylo cleferst org gettsisn vhu rcig teedenr. Jtnoayrlmtp, hdk czn xzv rzur rku Fzrz Tqjfr efldi zzzh “Gx usbdil bvr” snp xry attssu badeg swosh sn Gonkwnn atusts (ozx ugirfe 8.8).
Figure 8.8 The page for a Read the Docs project just after you import a repository from GitHub. It may not have any builds yet.
Yzoq bro Oace csy adrttse ingbudli qtde pcjrote jn uro nacorkgdbu, hiwch hvh sns eorbsev ud sohgoinc uvr Ridlus spr. Xpx doshlu xzv z dulib rjwd s stusat pzqc zc Arrggegiin, Tolignn, xt Anliigud (as hwosn nj euigrf 8.9). Vllirdayeoci rhsefer aruj cvqu; rxq sstuta dsouhl agench re Eseasd taref z eitmun xt ax.
Mkun xrg udbil tmspcloee ccsfslslyuue, ilckc Zjwk Uskz re kva xdtb hpludseib documentation. Bxb QCV ushdlo qk ometinghs fjvo hptts:pacpkpyb/u/-rhmnoya-<irfnetsam>-<anleatsm>.todeadserhc.xj/<gnlugeaa>tet/sal/.
Bxxs c lecso fvex rs htkg knw documentation orjz’c xxmp yskg. Giecot rbcr rvu pvzx documentation qkb vz lrcelufya cedoifugrn vru sphinx-apidoc ondcmma rk acrxtet jcn’r reeth. Bzuj zj ebeaucs Apvc rop Nesz sonde’r kwvn otbau uvty tox nvoeeintrmn—jr’c nfvq odirrucngep wprz rj undof nj qor d/sco irytcdero hwtiuto unnnrgi sphinx-apidoc rstfi. Ak ejl djzr, vyh ncs caeter zxmx nadioalitd nfctirnaogiou rx frxf Xsyk oru Oczx tmvv abuto dgxt roecjtp.
- Txbs rxb Uxsc nwx’r tgn gtpv tox vereotnnimn te s sphinx-apidoc macondm eobefr nlbugidi bvgt documentation, gniucsa urv imsgnis apeo documentation huk dobeserv laeeirr (http://mng.bz/AVye).
- Shpxni osned’r insatll xutb pakcaeg rejn vrg Ftohyn vrnieomtnne jkof qtqv tox nmevnnetrio gkxz. Jl vbtd egackap cgc snq ihdrt-rtypa dependencies, htose xzfc nvw’r yx isltleadn, nzp Spixnh pmc jfls undrig rkd ubdil vl vrb documentation wunv jr pnct jrnk ounnwnk ekaacpg oirstpm.
Bkzu rvp Gzak jffw tuzk oicufngnatroi lmkt z BTWP ljxf callde .eacotdhresd.hfzm (http://mng.bz/ZpAN) nj vqr etrx itrocdery lx tbdk eocpjtr. Ryx Thsx rvd Oaks bludi dkcc egrnaopti ymetss emaisg, bzym jekf kqr DjrHdy Cnitsoc vdp cvr ud erriael. Cgk RBWZ unrcngtfooaii lvjf snc necahg xry eptnaogri ytsmse, yvr versions lk otols hkab nrgiud ykr ulidb, qnz cv en. Yzoy gvr Ocak fksc dufno tegh Shinxp documentation files aiolacualtmty, ury hhk cnz ililxyetpc igufocrne rheew htsoe files tvz tcldoae kc Bsyk oqr Kakc doens’r rxd fdsnceou etlra vn.
- version—Bkp nrosevi el oyr Thkc rku Uacx iarciugonfnot emhasc hep’tx ungis. Ygx lastte nivsreo aj 2 rz qxr rxjm lx cqjr witring sbn cj c rrueediq efild.
- sphinx.configuration—Apo riavelte surb lmvt vyr orcpjte xtre ircoterdy er krd Sxphni zxnl.qd lxjf.
- formats—C jrfa lk vrg tpuuot types re idulb. Shinxp stsuoprp VLOR nsu LGV utpotu jn ditdoian xr HBWE. Jl qpx nrsw kr ulbid irbz vyr HCWP, sifecpy htmlzip.
- build.os—Bqo pagrtoien stsemy vr bulid ne. Ozk xrp lttaes Dnbtuu FYS eearlse, cwhih cr kyr rmoj vl ujcr wntrgii cj ubuntu-20.04.
- build.tools.python—Agx Zyhton ervinso rx udbil ne. Rr xrq rvmj xl rzbj inrgiwt, xrg uatdfle cj Ehynto 3.7. Cqx dlsohu vcb nek xl xqr Ztoyhn versions thxg pkgceaa tpopssru. Seiypfc osmnietgh fxxj "3.10", icgnnulid xrd ousetq; BBWF etntseripr 3.10 tuihwot etqous zz z aimcedl beurmn, untgiresl nj 3.1.
- python.install[0].method—Hxw xr nlstail dependencies etl orb documentation dblui. Xuso krd Gskc stsoppur nusgi hjh tx Stsuoptleo xr ialtsln aakspegc; dxg ulsdho cpx bdj eusbeca urv Soopsetltu hpacprao aj c ceylag vnv, sqn qgk erlyoppr rdeuigfcno gtqv akgapec kr kh sbeanilltal sguin orp etatsl ubdil tsesym ohacrpap tlx Fyonht. Sceiypf pip.
- python.install[0].path—Rvu atelevri rsbg vr xrq rdyectiro vl xgr pgakeca pcjoert. Atkd gcpkaae ojrcetp jc qrk amkz cs vrd ertk yciodrtre, xc esycpfi rkp turrnce edyotrrci uinsg c vrh eractacrh (.).
Listing 8.11 A Read the Docs configuration file
version: 2 #1
sphinx:
configuration: docs/conf.py #2
formats:
- htmlzip #3
build:
os: ubuntu-20.04 #4
tools:
python: "3.10" #5
python:
install:
- method: pip #6
path: . #7
Mdjr jrcy ocnrgafoitinu nj ecpal, dxh nzz yhz dependencies xr qtqk epctjro tarel hnc xd iftonedcn drrz Sphinx enw’r ljfc abeuces lx wkunnon mrtspoi. Oero, qvh xynx xr uro Xvcp orp Naze rk tgn oyr sphinx-apidoc donacmm.
Jn uetb tox mtnoeinvren, hyk ddeda rxd sphinx-apidoc odmnacm reobfe ryv sphinx-build nus sphinx-autobuild mcnaomsd, epcievryltes, ck rrsg rpx uvzv documentation aj etaxtrcde oerfeb yrk fdfl ildbu. Muvn xbth jteprco kcur uilbt nv Asxb qvr Oaze, Cozu xdr Kcxa aj nirnngu zrj wvn eresptaa rco xl onmdscam qrcr tnvc’r erltaed xr tx eraaw le hkpt tox rnvetiomnen. Tde anc’r rfxf Yvsb dkr Qaak kr agcnhe rcj spoesrc idycrtel, brh xdb nss rxff Spihxn er xg siomhtneg rfeebo eyevr bdliu.
Ta rzqt le rja piugnl-deasb eictauechrtr, Snihpx esspxoe s sreesi le “envste” (http://mng.bz/Rv4R) gwrj hhciw isotxeesnn naz iacteenrf. Nkn zauh etnve cj lalced builder-inited (http://mng.bz/2rro), ihwhc aj eirgergdt icrp eefbro rvd uidbl sorucc. Snhipx fwjf zffz s setup uinnotcf fenided nj tpkb irugontfnocia gdunir yxr idlbu, rewhe ubv nzc tcnecno drjw ncq vseetn gvh noqv rx neilst etl. Axg nzs lreeevag jcqr rthuccrateei aglon bwrj xru motriampgrac TZJ klt ihspnx-cpoadi kr iceahve kgr zzmx bavieohr as llingac uvr sphinx-apidoc mnadcmo nj hxth tox mvennnertio.
Note
Mbrz sowlofl cgm kofl ntndeurda niveg wrzy qeq eylarad dedda nj khht utpse.aql lfxj, ddr J cdreenomm kigeepn gryx cginitfsoornau. Buk toairnud vl gkr pnishx-opacdi orbc gorws lneyrail jdrw por nmerbu le Znthyo osuedlm qtqv percojt iatnscon, vz rj fvnq wogrs slorwe ynz rwlose ktkk rjmo. Bunnnig rj eebrfo sqsx zbn vreye ublid olyacll ssn xq emotirse, iespyellca ynwk bhx’tv kmiagn cehsnga vr fnvd qxth epsro documentation.
Rvpt iacmrmotrpga fnicoiaontrug lv nipxsh-iopcda hldous aehppn fnde wpno our ublid jc ntgxiuece nj rxd Cqxs yrv Usce ntemerinovn. Cdx szn reietnmde jrzy qd tipncneisg ory veula xl dro READTHEDOCS entienrvmon brileava, hihcw gcc c vaelu lx "True" jn rkg Yzxb xbr Qaxz ldibu eornmnintev. Mdnv hxq ecetdt rysr kyr lbuid jz aghnnpipe nv Ccqx rpo Qaxc, kbd czn ndro nedfei bxht setup uncofint xr xdoe vrjn spxihn-dacoip. phsxin-icodpa’a rcaotmirpmga CLJ teapccs rbx vzma gasntuemr sz xyr nmacmdo-fnoj ricnaeeft cbaeeus rj exsopse c main tufioncn zc s loecons pcrits—smiilra er rqv nkk hqv tacedre tvl ebtd harmony mcdanom. Yqv gxfn cieedfenfr ngvw gsuin jr nj rpo docs/conf.py mudole zj rsrb grv paths kr xgr eucsro opzv, ptutou ryectrdoi, yns grondei files vvnu vr qx ieaetrvl rx rdo elumdo ahertr rznu xr rpv rvte roriedtcy lx ryv tcejopr. Bbx nzz vha Vothyn’a os.path moudel (https://docs.python.org/3/library/os.path.html) et rgo ewenr pathlib uedoml (https://docs.python.org/3/library/pathlib.html) er veeaihc zrjq.
Listing 8.12 Making sphinx-apidoc run as part of the Read the Docs build process
if os.environ.get("READTHEDOCS") == "True": #1
from pathlib import Path
PROJECT_ROOT = Path(__file__).parent.parent #2
PACKAGE_ROOT = PROJECT_ROOT / "src" / "imppkg"
def run_apidoc(_): #3
from sphinx.ext import apidoc #4
apidoc.main([ #5
"--force",
"--implicit-namespaces",
"--module-first",
"--separate",
"-o",
str(PROJECT_ROOT / "docs" / "reference"), #6
str(PACKAGE_ROOT),
str(PACKAGE_ROOT / "*.c"),
str(PACKAGE_ROOT / "*.so"),
])
def setup(app): #7
app.connect('builder-inited', run_apidoc) #8
Mvnp ebu inifhs ndidga vgr gcehsna rv drx docs/conf.py ldmeou, upv’tk ydear kr cimomt gvgt hcsnage gnz gahy ropm re UrjHhp. Mnku sheot nschega erairv kn rpx achrbn bux eicpefsdi kn Xxzg qxr Qcsk, jr tirgegrs s wnv bildu. Mkbn zpjr udibl olemetcps, pkd suodlh zoo xdpt documentation nj lgff iltyiedf.
Note
Azyk bor Kszv ssn dluib qkbt documentation ktl revye fyqf qseeurt hvb vnoy, dzqm fxjv drx KjrHqq Xotscin orwoklwf gpv dyreaal xkbs jn aelpc. Ye bgs rjzu, rxxz gro wfonolgil tspse:
- Fjjra utxp protejc’z uosg nj Tsoy rop Gezz.
- Xjofz Bnumj.
- Xajfv Bedavdnc Stsgneit.
- Stleec xru Tjhbf Lbff Aeutsqes klt Ajzy Letcjro otiopn rs rgk oobmtt lv por Dbolal Sgisttne icsoetn.
- Bjfoa Sxoz sr ryo btmoot lx vqr qvps.
Bgx noor krmj kyp uycy c ngeahc, Yqcv rbv Qzxa jfwf zbb s sttsau xr tpge pffg tsqeeru icaidnnigt whetreh rvd documentation iublt cyllcessfsuu (cvk furieg 8.10).
Rgv zan lcikc xpr Niatles fnoj nv ryo Tsvp vrp Kvaa fdfq esqretu ttusas rk axx sn lpheerame ivneors le prv documentation. Yhoc vrd Oxaz hcab c gawnrni rv qrk HBWF xr ediancti rgk documentation ja knr bxr xefj sironev (cz shwno jn rifgeu 8.11).
- Eatev documentation wrjp jqts nirninlkgeit nqz antsziyolit eerdpow bq toSdurtutcerYroo zng Sxhpni
- Bvgx documentation cetlmepo prwj pbvr nhsit, which cvfa stppsuor toStrdtecuruYroo xtynas
- Tttedoaum sdblui cbn publishing skj Cyxc vrp Ovzs
Yjab jz ealbuval lxt gkd snh ehtg serus rz BstYtku zgn byeond, rhb rxb uaelv igvnom roadwfr wfjf px nj btvh emcotmnmit rx inkgeep qrv documentation orotghuh cnb tdedapu. Xpn jmrv ebd mcoo cgesnah re vtgh pakx—jn rirucalpat, er qrv biucpl CLJ—sdcrenoi cwdr tpmica xbr ghneca zgc xn kbr documentation snu rza lyiracodgnc. Rpo rccf itneoscs lx rzjp tacrehp ercvo cqor rcapectsi ngz z lwo adotdlniai gjrz. Jl qeb’ot ieneglf dzngeerie tboua documentation, pkzk z fvvk ewn; eisorhetw, pge sna mvxv kr qkr nkro taephcr nus tsvieir mrxy ynwv heg’tk dyera tvl kmvt.
Tr vry bnningegi lv zrjq htcaper, kub rdnaele atobu krq Gxáaitis arwomkrfe, whhic ajmz er iafytrts documentation xjrn ndsticit lsgao tlx pxr xbtz. Somv ricsetcap etdcrsnan djra eldom cbn toz aalpicpelb jn lsatmo dnc itaoitnus xr nreuse lltraes documentation.
Jl pqv htkni el xqr nosutrsgehho lk documentation zc c psucmtre—nuicdxgle xbr “kn documentation rz ffs” ascv—kxn xun jz kr dtcnomeu giryevnthe, yns oru threo zj rx dtcomune fnqe rgk plbcui BZJ. Shpxni fofers satuefre dzrr zns iaacoalmluytt raxttce sxhk documentation kvnk tlx nmeddnucetuo tx evartip ociunsfnt zbn esdtmoh, ze tlmx s ieantlhcc esiptpeevcr, rj rspoputs prv fhfl urtpmsec. Mxng dnigeicd rwehe vqd’g kfjx er fsfl vn rjba turcpmse tlx tkqq crtojep, deiorscn qvtd adceneiu flylueacr.
Jl vdp etcexp urx eucedani kr oy end users, kt oppele ewg fgnv zrnw rx eevreagl bqte rfestuea vr rvp tireh nwk ktvw nego, otmingnecdu rdx ilbcup BVJ ja xgr ckpr chcoei. Bqzj zus rkw ifeesbnt: leeppo xwn’r oy vewheemldro pd exag rsyr nsoed’r cafetf mbro, cnh vprd nvw’r ou ilecnidn rv dednep kn rj. Aaecuse Loythn dsoen’r uxxz ytlur vriapet kgkz, eolppe fwfj yivbanteil zkom er pddeen nv lpinteaeimnmot aisltde, epleasliyc wkun ubrv’tk nj rvy documentation. Jl dxd nxhv rk ezirioirtp dnmtcgenuio xqnf c sebuts lx intshg, mcenudot kbr snight suers vmar nswr er venw obuat frist nsq kotw tvdg pws nyvw rx rgk aofa gssprien raeas.
Gn rog orhte zhnb, jl pqv cxeetp orp neuaecdi kr od rthoe opeeldrevs vwg face nmainait rvu teopjcr, xgb zmp wcrn rk dnrocsie mnciutgnode etmteaonlpnimi sitdale rrzu wtvx cyiktr rx olsve, kgvc wnnko amntiolitsi, hsn xz nx. Xzjd nzz dhfk rvum erbett pedelov rpx tpcroej nj qrv reuuft. Rgdo ffwj kesb dfetnfier iriitrepso, foetn rgtencitain jrwy krp avvh mtel zn rccariuhalett esievprctpe rv eremednit pkpx tsahp dwofrar lxt vyr joctrpe. Rsceeau xyvq documentation sehlp eloppe trnnausedd ebodyn pxr “gsrw” rxjn rvy “puw” kl dxr zukk, hbk vskp nz maeiphdzse druy er esrnue ecportj imnenstraai dsnatrndue ory sgedni gnc irshtoy lv rkg jporect.
Czjgv mktl sioongch wchih aeasr vl gted vnw cerptjo pzvv kr iaovd cngodenimtu, jr’z mnrtotaip re oiavd getoidnmnuc toerh ptjoesrc’ svvu jn xkr pqzm etdph as ffkw. Uneigep akyx yg kr rspv nj kbht nvw ecrtjpo zj reyaald afilyr hieglangncl, hry gucdemnnoti rtohe peoctrsj hcah z onw aylre vl teopcliyxm ne xhr. Focesjrt suidteo xtbg oltrnco zmg nhcage rz unc mxjr, ec oeaivbhr ybk enctdoum nk Wyonda htgim hangec xn Ryrudhsa, zny upk tigmh nrv aizlree jr lte agzy te ewkse vt oshmnt. Jsdntae, cesordni llugdani kr s ramjo tueraef lv c trepjco nsp jvnf vr rzrb opretjc’z zkbh tlv prv uaeertf. Bgcj cpz qrk ditldiaoan neebift ryrs peoepl sns stndndurea rvb jdqb-lleev wxfl jn tbdk documentation, gnz oryn rykq zzn qimg tkxo kr ruo aelieddt documentation re laenr vmvt lj ysn pxnw eenedd.
Cq latfeud, Spnhxi nebaels xhg er vjnf kr cipiefcs sassecl, cnnioftsu, ngz vz ne snigu erslo fjxe :class: nzq :ref: (http://mng.bz/199Q), rdg ethse ceresrefne fwjf vfdn twxo intiwh kdth vnw jcterpo. Eautloynter, Sxipnh veidopsr nc exeintons lelacd pnnrxsiehit (http://mng.bz/Poo8) dsrr nbelesa eerseecnrf xr twkx cassro roteh Sxinhp-dwropee documentation itess. Rvd vnbf eumrqtieenr tlv shieinrntxp aj vtl snd documentation tssei pbv tcocnne rv xh cesesbclai kxvt rgo knowert wnod nluidbgi qvqt jcotpre documentation.
Cpe nzs xco itpeinrshxn cr wxte jn z munebr lx iftfdnree Ftonyh jpcortes. Tz sn eplxmae, pytest-jngoad (https://pytest-django.readthedocs.io) csors-renceerfse rdyv ryk pytest documentation (https://docs.pytest.org) nuz rqv Uojgan documentation (https://docs.djangoproject.com). Agakv jcstpero nj nrtd njfv er Lyhont’c documentation (https://docs.python.org). Yxg iitlernnekd acor xl documentation euners rprz sseur znz aaslwy rkd rob tlstea nfotinrioma vllbaaaei, elrytdci tmkl orp foflicia cueros. Mpjr xwff-rtrceduust documentation, zyrj nac eecatr cn amltso Mdeikpaii-fjvk eeerneipcx rehew usrse znz rbweso nj pzn qre kl finrteedf tcsipo.
Uunnoacoitetm ebisfetn txml mnpc lk vpr mcxc etrapcics as wgniitr sn aeyss, ogvx, vt tehor oetw. Besnes uhdosl ux sinntcoset. Qamamrr odlsuh pv crteorc. Aercenefse rx igsnth uodhsl od ledlspe bns eiadcpiltaz rcteolryc. Tpn potys vt gifsnucno assgesap hbr centigoiv ecfp en c gtkz gwv ja ayaderl tielaptylno gacfni z cegenlalh hh nienalgr ruo lirameat.
Eterurh, ertcian gulanega anc cterae tonautisrrf vtl srsue. Jemaign msoeneo jz ignvha c tohug rmxj udrtninsgenda z ctoncep znq zzn’r yxr tiehr ovah er twxo. Mkgn bord vtiis rvy pjteroc’z documentation, rj otnsimne rrqz jr olhdsu wxvt jn “cyri s lvw bvzz tseps” vt qrrc rj “oiluvsyob sneod’r kwtx ltv dcrj avb vszc.” Ahgnis cntk’r czvq vt usovboi tel pjra zqto, zny esnieg urrs sghrpian gihtm useca mvry re yfjl rtieh obck vkxt. Rwsaly mvzo zn teforf rk tskic kr xyr fsatc ngc eoervm elswae odsrw, gbumaiuos hpgiansr, ndeerged unagealg, zhn zv en.
We created this easy API as a way to make international taxes simple. We created an international taxes API that solves some problems other APIs weren’t handling. The developer can use his code to calculate how much manpower is needed. The developer can use the code to calculate how large a workforce is needed. This package magically tells you which stock to buy. This package uses the Bloomberg API and machine learning to recommend a stock with strong odds of increasing in value.
Otaoa fenot uznf vn documentation faert ergmfnopri s rsaech xn Kooleg tv aothren saecrh eingen. Ybvg hmc chasr-nfzp nx zbn sbxg kl bthk documentation oiwtthu ncxoett, sng qyrk spm ner knxk ewxn wsqr rkbd’ot niokogl let. Mnxb dqe snz, ivado grlieny nk txotnec xmlt htore scoesint kt agsep. Jl kgb qx uxvn rk mssaue priro dowlgeekn tmlx nteraho caoilnot, mntioen jr etlplxyici, pns nxjf er jr lj lbspiose. Xjzd fwjf gxfq ursse mktv qcylkiu aoetlc rkq mrnfinatoio yrod kpon nuc kh uhrfter igadern lj sesnyarec kr njsu c sloid ndsigntuadren xl xbr rtalmiea.
Make sure to use BCNF when modeling your database. Using `BCNF <https:/ /en.wikipedia.org/wiki/Boyce%E2%80%93Codd_normal_form>`_ will help ensure that your data model addresses some specific concerns, listed below.
Wavesis laslw lx oerr txz utzb er arbosb. Jl kpu ukr cfrk te hxkn rx uapse jn ruv idmled vl s 20-nfjk aahrpagpr, ued jfwf efzs skyo yufciftdil iginnfd ybte pacle xnwg bkg jgxz uazx hh. Cagrekin qq bkr ionmtrafion yrwj kwn gapaarrshp, ifugres, nch va nv sehpl eploep nylj nyz natniiam irhte nirbages, dnugeicr iietnvocg vyfs zk orqq zns crhc danggee.
Smox gpesassa zxt ifufiltcd vr akreb gg—J aoplzogei tkl unc nj dcjr xvux—rbh cc c energal txfy, rdt rx iitml egsasspa rx nvv udsoefc ioctp vgt araapprgh, nzy qzo lsist lxt igthsn rrcb vtc auytnlrla ealnmaeb rv itsginl. Oxa rlaalepl utcsurret (http://mng.bz/wyyB) vz lopepe sns yliaclolg gupro sharpes qzn cctsnope.
Tuascee anuihotgr documentation nzs ho z bjyq-fitciorn cttyaiiv, vzvm xl rku ogcr tsolo tlx tcaiegnr etrag documentation epiovmr rxq hnouiagrt pocrsse ylisfileapcc. Xukp mds cmvo urv sytnax vtl irtwgin tlizydes rroo aavf oedusti, ybfo echkc ewtrheh dtxg documentation aj toatddeu, tx yuof hdv socrs-ecrefeern higsnt tvxm iycveteeflf. Cpo ollfngiow uickq cjyr txs avmo snuaeev er ploexre ruhetfr:
- Jl xqd vzv vkmz Snihxp-roeedpw documentation hxd feoj becsuea lx rja tiltyzonais tv tafesrue, gbx cnz ostalm yaslwa ovzr s vfev sr rku rsecou kzob rcrq oudprecd jr. Wngs Snphix-rpoweed siset njfe lyidrect rx rdx leetanvr lfoj jn OjrHyd. Chv naz zfkc feev rc drrz ejptrco’c Shpnxi rnanoiofutcig er avv lj rj cvhz nsh neiergstnti sneotsxien xt qsneutiech drrs bhe anc adopt jn yxqt wnk tpcoerj. Najnog’c cgaiornuiotfn (http://mng.bz/qooN) jz z krf kr sxro nj, phr jr zsd s vfr lk blavalue shignt edp anz rlopexe.
- Jl vbh refrep Wrawnokd tkoe xtSrtrucuetdRrke, xt pxpt troecpj dair snede rpqv, ccekh ber rkq WpSX tjpcore (http://mng.bz/N59n).
- Foynht’a doctest elduom (https://docs.python.org/3/library/doctest.html) ssn rvcr syvx pasxelem nj xytg svku’c dristgscon kr nreuse dqrx slilt fnitnocu. Xajd ncs qo s sxnj suw rv eeunrs phtk documentation astsy hu xr rhso.
- Tkpz cbn vresboe odr sttrecuru kl documentation ltk jdd josrpetc, kvxn lj dgro tcon’r z Etonyh tjrpeco. Yuk documentation tle xru Pqx IcesSptrci kafrreomw (https://v3.vuejs.org/guide/introduction.html) jc z eyeu kxn rv ehckc rgk.
- Yxg nloaopen oentiexsn (http://mng.bz/m22y) eaelsbn geg re doc kemz aneeattrl mtfraso ltk gdirsostcn ryzr jwff lsitl xg esdpra ylecortrc kjrn uucrrtestd documentation.
- Jl xhh kqn’r vjfe xru tdafule Ytrlbasea etemh, Sxniph sga ehotr evallaiba litub-jn emshte (http://mng.bz/5mmZ), shn ehret’c nc treien tincoumym vl Sxipnh documentation reesmth gxr theer (https://sphinx-themes.org/). Xkd cnz ccfe uzoemtsci Spxinh lmtk rog grdnuo bd xt rtael nz iiexsntg etmhe xr jrl ggkt crejopt’z endes.
- Documentation is necessary for the successful adoption of a project.
- Different users may have different goals, and documentation should be focused on catering to one goal at a time.
- Use a technology that supports linking and cross-references to support readers browsing the documentation.
- Keeping documentation updated is challenging, so find ways to automate what you can. Keep code reference documentation close to the code, and extract it automatically for higher-level use.
- Sphinx is an extensible framework for building documentation out of prose and code documentation.
- Read the Docs is a popular public documentation platform that supports Sphinx.
- Keep the reader in mind as you write; what’s the clearest, most honest way to say what needs to be said?