Kas yra standartinis „Python“ dokumentavimo formatas?

Aš mačiau kelis skirtingus rašymo stilius „Python“ dokumentams, ar yra oficialus ar „nuoseklus“ stilius?

626
10 окт. Noah McIlraith, spalio 10 d 2010-10-10 04:10 '10, 4:10, 2010-10-10 04:10
@ 8 atsakymai

Formatai

Python dokston galima rašyti keliais formatais, kaip rodo kiti pranešimai. Tačiau numatytasis dokumento formatas Sfinksas nebuvo paminėtas ir pagrįstas reStructuredText (reST) . Jūs galite gauti informaciją apie pagrindinius formatus šiame tuto .

Atkreipkite dėmesį, kad reST rekomenduojama PEP 287

Po to seka pagrindiniai formatai, naudojami dokumentuose.

- „Epytext“

Istoriškai javadoco stilius buvo platinamas, todėl buvo sukurtas kaip pagrindas Epydoc (su pavadinimu „ Epytext formatas) kurti dokumentaciją.

Pavyzdys:

 """ This is a javadoc style. @param param1: this is a first param @param param2: this is a second param @return: this is a description of what is returned @raise keyError: raises an exception """ 

- poilsio

Šiuo metu greičiausiai dažniau naudojamas reStructuredText (reST) formatas, kurį „ Sphinx“ naudoja dokumentams generuoti. Pastaba: pagal nutylėjimą ji naudojama „JetBrains“ „PyCharm“ (po to, kai apibrėžiate metodą ir paspauskite „Enter“). Jis taip pat naudojamas kaip išvesties formatas „Pyment“.

Pavyzdys:

 """ This is a reST style. :param param1: this is a first param :param param2: this is a second param :returns: this is a description of what is returned :raises keyError: raises an exception """ 

- „Google“

„Google“ turi savo formatą, kuris dažnai naudojamas. Tai taip pat gali interpretuoti Sfinksas.

Pavyzdys:

 """ This is an example of Google style. Args: param1: This is the first param. param2: This is a second param. Returns: This is a description of what is returned. Raises: KeyError: Raises an exception. """ 

Daugiau pavyzdžių

- Numpydoc

Atkreipkite dėmesį, kad „Numpy“ rekomenduoja sekti savo „ numpydoc“ naudodama „Google“ formatą ir naudodama „Sphinx“.

 """ My numpydoc description of a kind of very exhautive numpydoc format docstring. Parameters ---------- first : array_like the 1st param name 'first' second : the 2nd param third : {'value', 'other'}, optional the 3rd param, by default 'value' Returns ------- string a value in a string Raises ------ KeyError when a key error OtherError when an other error """ 

Konversija / karta

Galite naudoti tokį įrankį kaip „ Pyment“, kad automatiškai sukurtumėte „Python“ projekto dokumentą, kuris dar nėra dokumentuotas, arba konvertuoti esamus docstrings (gali maišyti kelis formatus) iš vieno formato į kitą.

Pastaba Pavyzdžiai paimti iš „ Pyment“ dokumentacijos.

669
24 июня '14 в 14:10 2014-06-24 14:10 atsakymą pateikė daouzli birželio 24 d. 14 val. 14:10 2014-06-24 14:10

„Google“ stiliaus vadove yra puikus „Python“ stiliaus vadovas. Jis apima konvencijas, skirtas skaitomoms teksto sintaksėms , kurios siūlo geresnes gaires nei PEP-257. Pavyzdžiui:

 def square_root(n): """Calculate the square root of a number. Args: n: the number to get the square root of. Returns: the square root of n. Raises: TypeError: if n is not a number. ValueError: if n is negative. """ pass 

Norėčiau ją išplėsti, kad į ją būtų įtraukta ir tipo informacija argumentuose, kaip aprašyta šioje „ Sphinx“ dokumentacijoje . Pavyzdžiui:

 def add_value(self, value): """Add a new value. Args: value (str): the value to add. """ pass 
299
13 нояб. Atsakymą pateikė Nathanas lapkričio 13 d. 2011-11-13 06:14 '11 at 6:14 2011-11-13 06:14

„Docstring“ konvencijos yra PEP-257, turinčios daug daugiau informacijos nei PEP-8.

Tačiau atrodo, kad doktorantai yra daug labiau asmeniški nei kitose kodo srityse. Skirtingi projektai turės savo standartą.

Aš visuomet visada įtraukiu doktronus, nes jie linkę parodyti, kaip naudoti funkciją ir ką jis daro labai greitai.

Norėčiau išlaikyti nuoseklumą, nepaisant eilutės ilgio. Man patinka, kaip kodas atrodo, kai įtraukos ir tarpai yra nuoseklūs. Tai reiškia, kad naudoju:

 def sq(n): """ Return the square of n. """ return n * n 

Per:

 def sq(n): """Returns the square of n.""" return n * n 

Ir, paprastai, neturėtumėte komentuoti pirmosios eilutės ilgesnėse dokumentuose:

 def sq(n): """ Return the square of n, accepting all numeric types: >>> sq(10) 100 >>> sq(10.434) 108.86835599999999 Raises a TypeError when input is invalid: >>> sq(4*'435') Traceback (most recent call last): ... TypeError: can't multiply sequence by non-int of type 'str' """ return n*n 

Tai reiškia, kad manau, kad dokumentai, kurie prasideda tokiais, yra purvini.

 def sq(n): """Return the squared result. ... 
218
10 окт. Atsakyti Tim McNamara 10 spalis. 2010-10-10 08:36 '10 8:36 val. 2010-10-10 08:36

Kaip matyt, niekas to nepaminėjo: taip pat galite naudoti „ Standard Docstring“ . Jis plačiai naudojamas mokslo bendruomenėje.

„Napolean Sphinx“ išplėtimas, skirtas „Google“ stiliaus dokumentams analizuoti (@Nathan rekomenduoja atsakyti), taip pat palaiko „Numpy“ stiliaus dokumentaciją ir trumpą palyginimą .

Ir paskutinis pavyzdys, rodantis, kaip atrodo:

 def func(arg1, arg2): """Summary line. Extended description of function. Parameters ---------- arg1 : int Description of arg1 arg2 : str Description of arg2 Returns ------- bool Description of return value See Also -------- otherfunc : some related other function Examples -------- These are written in doctest format, and should illustrate how to use the function. >>> a=[1,2,3] >>> print [x + 3 for x in a] [4, 5, 6] """ return True 
44
21 апр. atsakymas duotas joris 21 Bal 2014-04-21 03:01 '14 at 3:01 2014-04-21 03:01

PEP-8 yra oficialus python kodavimo standartas. Jame yra skyrius apie doku mentus, kuriuose kalbama apie PEP-257 - visą specifikaciją dokumentuose.

13
10 окт. Atsakymas pateikiamas 10 val. 2010-10-10 04:48 '10, 4:48, 2010-10-10 04:48

Oficialūs Python stiliai yra išvardyti PEP-8 .

4
10 окт. atsakymas duotas gintaro 10 okt. 2010-10-10 04:21 '10, 4:21 val. 2010-10-10 04:21

Siūlau naudoti Vladimir Keleshev pep257 Python programą, kad patikrintumėte savo dokumentus apie PEP-257 ir „Standard Docstring“, kad apibūdintumėte parametrus, grąžą ir kt.

„pep257“ praneš apie skirtumą, kurį padarysite iš standarto, ir yra vadinamas „pylint“ ir „pep8“.

4
11 сент. Finn Årup Nielsen atsakymas rugsėjo 11 d 2014-09-11 18:34 '14 at 18:34 2014-09-11 18:34

Tai Python; viskas eina . Pagalvokite, kaip publikuoti savo dokumentus. Dokonas yra nematomas, išskyrus jūsų šaltinio kodo skaitytojus.

Žmonės tikrai mėgsta naršyti ir ieškoti interneto dokumentų. Tam naudokite Sphinx dokumentacijos įrankį. Tai de facto standartas Python projektų dokumentavimui. Produktas yra gražus - žr. Https://python-guide.readthedocs.org/en/latest/ . Svetainėje „ Skaityti dokumentus“ jūsų dokumentai bus paskelbti nemokamai.

4
11 янв. Atsakymą pateikė pulkininkas Panicas 11 sausis. 2013-01-11 22:29 '13, 22:29 pm 2013-01-11 22:29

Žr. Kitus klausimus apie „ žymes. arba užduoti klausimą