Bir yöntemle parametreler nasıl belgelenir?


139

Python'un belge dizelerini kullanarak yöntemleri parametrelerle nasıl belgeleyebilirim?

EDIT: PEP 257 bu örneği verir:

def complex(real=0.0, imag=0.0):
    """Form a complex number.

    Keyword arguments:
    real -- the real part (default 0.0)
    imag -- the imaginary part (default 0.0)

    """
    if imag == 0.0 and real == 0.0: return complex_zero
    ...

Bu sözleşme çoğu Python geliştiricisi tarafından kullanılıyor mu?

Keyword arguments:
<parameter name> -- Definition (default value if any)

Biraz daha resmi bir şey bekliyordum gibi

def complex(real=0.0, imag=0.0):
    """Form a complex number.

    @param: real The real part (default 0.0)
    @param: imag The imaginary part (default 0.0)

    """
    if imag == 0.0 and real == 0.0: return complex_zero
    ...

Çevre : Python 2.7.1


1
PEP 257'yi okudunuz mu? python.org/dev/peps/pep-0257
NPE

1
Orada birkaç 'standartlar' var ama pratik bir yaklaşımda ve özellikle resmi bir şeyden hoşlanıyorsanız, sfenks tavsiye ederim . Pycharm'a entegrasyonu, iyi yapılandırılmış öğretiler üretmeyi oldukça ağrısız hale getirir. IMHO
jojo

Yanıtlar:


86

Deneyimlerime dayanarak, numpy docstring konvansiyonları (PEP257 superset), Sfenks gibi araçlar tarafından da desteklenen en yaygın takip edilen konvansiyonlardır .

Bir örnek:

Parameters
----------
x : type
    Description of parameter `x`.

2
Bu beklediğimden daha yakın. Ne yazık ki, düz PEP 257 seçtim ve kendi kuralımı ekledim (otomatik olarak oluşturulan HTML / PDF belgelerini kaybetme pahasına). Ancak, bir dahaki sefere bu çözümü seçeceğim. Teşekkürler.
David Andreoletti

5
Söylediğin öğretiyi işlemeye çalıştığımda, Sfenks şikayet ediyor SEVERE: Unexpected section title- Sfenks'i daha mutlu etmenin bir yolunu biliyor musun?
Brandon Rhodes

@BrandonRhodes bu bağlantıların bu kuralları Sfenks ile kullanma hakkında konuşuyor: github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt
Vladimir Keleshev

3
Aslında daha önce eksik bir alan var Description. Numpy belgelerini kontrol ettim, çünkü hemen fark ettim ve "Bir saniye, neden üç boşluk var? Bu çok garip. Kim üç boşluk kullanırdı?"
Zelphir Kaltstahl

6
Bu soru sorulduğunda en iyi cevap olabilir, ama sanırım şu an (2017 sonu), Sfenks galip geldi.
Alex L

120

Docstrings serbest biçimli olduğundan, API belgelerini oluşturmak için kodu ayrıştırmak için kullandığınız şeye bağlıdır.

Sphinx işaretlemesine aşina olmanızı tavsiye ederim , çünkü yaygın olarak kullanılmaktadır ve kısmen mükemmel readthedocs.org hizmeti nedeniyle Python projelerini belgelemek için fiili standart haline gelmektedir . İçin bir örnek tefsir Python pasajı olarak Sfenks belgelerinden:

def send_message(sender, recipient, message_body, priority=1):
   '''
   Send a message to a recipient

   :param str sender: The person sending the message
   :param str recipient: The recipient of the message
   :param str message_body: The body of the message
   :param priority: The priority of the message, can be a number 1-5
   :type priority: integer or None
   :return: the message id
   :rtype: int
   :raises ValueError: if the message_body exceeds 160 characters
   :raises TypeError: if the message_body is not a basestring
   '''

Bu işaretleme, belgeler ve daha fazlası arasında çapraz referansı destekler . Sphinx belgelerinin (ör.) :py:attr:Kullandığını :attr:, ancak kaynak koddan belge alırken kullanabileceğinizi unutmayın .

Doğal olarak, API'ları belgelemek için başka araçlar da vardır. Komutları kullanan daha klasik Doxygen var ama bunlar Sphinx gibi Python kodunu belgelemek için özel olarak tasarlanmamış.\param

Bir olduğunu unutmayın benzer soru bir ile benzer bir cevap burada ...


9
Bu, PyCharm'ın varsayılan olarak otomatik yorum oluşturması tarafından kullanılan stildir
Josiah Yoder

Malzeme listeleri gibi kompozit türlerin sözdizimi ne olacak?
matanster

o zaman bu bir list.
anarcat

33

Sözleşmeler:

Araçlar:


Güncelleme: Python 3.5'ten beri kompakt, makine tarafından okunabilen bir sözdizimi olan tip ipuçlarını kullanabilirsiniz :

from typing import Dict, Union

def foo(i: int, d: Dict[str, Union[str, int]]) -> int:
    """
    Explanation: this function takes two arguments: `i` and `d`.
    `i` is annotated simply as `int`. `d` is a dictionary with `str` keys
    and values that can be either `str` or `int`.

    The return type is `int`.

    """

Bu sözdiziminin ana avantajı, dil tarafından tanımlanmış olması ve açık olması, böylece PyCharm gibi araçlar bundan kolayca yararlanabilir.


12
Bu cevap şimdi en çok oylanan olmasına rağmen, yukarıdaki KEP'lerin hiçbiri bir yöntemin argüman türlerini belirtmek için bir kural sunmamaktadır.
koriander

11

python doc dizeleri serbest şekildedir , istediğiniz şekilde belgeleyebilirsiniz.

Örnekler:

def mymethod(self, foo, bars):
    """
    Does neat stuff!
    Parameters:
      foo - a foo of type FooType to bar with.
      bars - The list of bars
    """

Şimdi, bazı sözleşmeler var, ancak python hiçbirini zorlamıyor. Bazı projelerin kendi sözleşmeleri vardır. Dokümanlarla çalışmak için bazı araçlar da belirli kurallara uyar.



3

Ana akım, burada diğer cevapların da belirttiği gibi, muhtemelen Sfenks yoluyla gitmek, böylece daha sonra bu süslü belgeleri oluşturmak için Sfenks'i kullanabilirsiniz.

Olduğu söyleniyor, ben zaman zaman satır içi yorum stili ile şahsen gidiyorum.

def complex(  # Form a complex number
        real=0.0,  # the real part (default 0.0)
        imag=0.0  # the imaginary part (default 0.0)
        ):  # Returns a complex number.
    """Form a complex number.

    I may still use the mainstream docstring notation,
    if I foresee a need to use some other tools
    to generate an HTML online doc later
    """
    if imag == 0.0 and real == 0.0:
        return complex_zero
    other_code()

Burada bir örnek daha, bazı küçük ayrıntılar satır içi olarak belgelenmiştir:

def foo(  # Note that how I use the parenthesis rather than backslash "\"
          # to natually break the function definition into multiple lines.
        a_very_long_parameter_name,
            # The "inline" text does not really have to be at same line,
            # when your parameter name is very long.
            # Besides, you can use this way to have multiple lines doc too.
            # The one extra level indentation here natually matches the
            # original Python indentation style.
            #
            # This parameter represents blah blah
            # blah blah
            # blah blah
        param_b,  # Some description about parameter B.
            # Some more description about parameter B.
            # As you probably noticed, the vertical alignment of pound sign
            # is less a concern IMHO, as long as your docs are intuitively
            # readable.
        last_param,  # As a side note, you can use an optional comma for
                     # your last parameter, as you can do in multi-line list
                     # or dict declaration.
        ):  # So this ending parenthesis occupying its own line provides a
            # perfect chance to use inline doc to document the return value,
            # despite of its unhappy face appearance. :)
    pass

Avantajları (@ mark-horvath'in başka bir yorumda zaten belirttiği gibi):

  • En önemlisi, parametreler ve onların dokümanı her zaman birlikte kalır, bu da aşağıdaki faydaları sağlar:
  • Daha az yazma (değişken adını tekrarlamaya gerek yoktur)
  • Değişken değiştirildikten / çıkarıldıktan sonra daha kolay bakım. Bazı parametreleri yeniden adlandırdıktan sonra hiçbir zaman yetim parametresi doc paragrafı olmayacaktır.
  • ve eksik yorumu bulmak daha kolay.

Şimdi, bazıları bu tarzın "çirkin" göründüğünü düşünebilir. Ama "çirkin" in öznel bir kelime olduğunu söyleyebilirim. Daha nötr bir yol, bu tarzın ana akım olmadığını, bu yüzden size daha az tanıdık görünebileceğini, dolayısıyla daha az rahat olabileceğini söylemektir. Yine "rahat" aynı zamanda öznel bir kelimedir. Ancak mesele, yukarıda açıklanan tüm faydaların nesnel olmasıdır. Standart yolu izlerseniz onlara ulaşamazsınız.

Umarım gelecekte bir gün, böyle bir satır içi stilini de tüketebilen bir doktor oluşturma aracı olacaktır. Bu benimsemeyi yönlendirecektir.

Not: Bu cevap, uygun gördüğümde satır içi yorumları kullanma tercihimden kaynaklanıyor. Bir sözlüğü de belgelemek için aynı satır içi stilini kullanıyorum .


1

Parametre türlerini belgelemek için daha iyi yapılandırılmış bir yol sağlayan tip ipuçları cevabına ( https://stackoverflow.com/a/9195565/2418922 ) dayanarak, parametrelerin hem türünü hem de tanımını belgelemek için yapılandırılmış bir yöntem de vardır:

def copy_net(
    infile: (str, 'The name of the file to send'),
    host: (str, 'The host to send the file to'),
    port: (int, 'The port to connect to')):

    pass

kabul edilen örnek: https://pypi.org/project/autocommand/


1
Bu resmi bir sözdizimi mi? Süper yararlı, ancak resmi dokümanlar /
KEP'lerde bulamıyorum

1
Bunun için bir PEP varsa bunu da bilmek istiyorum.
DreamFlasher

-1

Docstringler yalnızca etkileşimli ortamlarda, örneğin Python kabuğu içinde kullanışlıdır. Etkileşimli olarak kullanılmayacak nesneleri (örn. Dahili nesneler, çerçeve geri çağrıları) belgelendirirken, düzenli yorumları da kullanabilirsiniz. İşte, her biri kendi satırındaki girintili yorumları asmak için kullandığım bir stil, böylece yorumun uygulandığını biliyorsunuz:

def Recomputate \
  (
    TheRotaryGyrator,
      # the rotary gyrator to operate on
    Computrons,
      # the computrons to perform the recomputation with
    Forthwith,
      # whether to recomputate forthwith or at one's leisure
  ) :
  # recomputates the specified rotary gyrator with
  # the desired computrons.
  ...
#end Recomputate

Bu tür şeyleri docstrings ile yapamazsınız.


46
Oh, bu çirkin gözüküyor.
Misha Akovantsev

1
Çirkin evet? İlginç bir fikir ... ayrıca evet.
David

2
Değişkenler için satır içi yorumlar çok mantıklıdır, daha az yazarak (değişken adını tekrarlamaya gerek yoktur), değişkeni değiştirerek / kaldırdıktan sonra daha kolay bakım ... eksik yorumu bulmak daha kolay. İmzanın altındaki uygun öğretiyle birleştirir. +1
Mark Horvath

Bu dokümantasyon olarak çalışmaz. Paketinizi bu şekilde yorumluyorsanız ve bir PyCharm kullanıcısı indirirse, belgelerinize erişmeden her parametrenin ne yaptığını kontrol edemez - ki bu da herhangi bir yazılımla oluşturamazsınız. Kendinizinkini yapmadığınız sürece. Bu yüzden OP doktora programında belirtilmesini ister. Çok geç özür dilerim.

Bu sadece korkunç.
Michael Walters
Sitemizi kullandığınızda şunları okuyup anladığınızı kabul etmiş olursunuz: Çerez Politikası ve Gizlilik Politikası.
Licensed under cc by-sa 3.0 with attribution required.