Python modüllerim için API dokümantasyonu oluşturmak için sphinx ve autodoc eklentisini kullanıyorum . Belirli parametreleri nasıl güzel bir şekilde belgelendireceğimi görsem de, bir **kwargsparametrenin nasıl belgeleneceğine dair bir örnek bulamıyorum .
Bunları belgelemek için iyi bir örnek olan var mı?
Yanıtlar:
subprocess-Modül belgelerinin iyi bir örnek olduğunu düşünüyorum . Bir üst / üst sınıf için tüm parametrelerin kapsamlı bir listesini verin . Ardından, diğer tüm oluşumlarını görmek için bu listeye bakın **kwargs.
subprocess.call(*popenargs, **kwargs). Tanınan anahtarlardan subprocess.call(args, *, stdin=None, stdout=None, stderr=None, shell=False)sonraki her şeyin (veya en azından sık kullanılanlar) olduğu belgelenmiştir***kwargs
subprocess.Popenve bunun artık özellikle harika bir örnek olduğundan emin değilim.
Bu soruyu bulduktan sonra, geçerli Sfenks olan ve oldukça iyi çalışan şuna karar verdim:
def some_function(first, second="two", **kwargs):
r"""Fetches and returns this thing
:param first:
The first parameter
:type first: ``int``
:param second:
The second parameter
:type second: ``str``
:param \**kwargs:
See below
:Keyword Arguments:
* *extra* (``list``) --
Extra stuff
* *supplement* (``dict``) --
Additional content
"""
Bunu r"""...""""ham" bir belge haline getirmek ve böylece \*bozulmadan korumak gerekir (Sfenks'in *"vurgu" nun başlangıcı değil, gerçek olarak algılaması için ).
Seçilen biçimlendirme (parantezli tür ve m-tire ile ayrılmış açıklama içeren madde işaretli liste), Sphinx tarafından sağlanan otomatik biçimlendirmeyle eşleşmek içindir.
Bu "Anahtar Kelime Bağımsız Değişkenleri" bölümünü varsayılan "Parametreler" bölümü gibi gösterme çabasına gittiğinizde, başlangıçtan itibaren kendi parametrelerinizi almak daha kolay olabilir (diğer yanıtların bazılarına göre) , ancak bir kavram kanıtı olarak bu, **kwargsSphinx'i zaten kullanıyorsanız , ek için güzel bir görünüm elde etmenin bir yoludur .
Sphinx tarafından ayrıştırılan Google Style dokümanlar
Sorumluluk reddi: test edilmedi.
Sphinx docstring örneğinin bu kesiminden , *argsve genişletilmeden**kwargs bırakılmıştır :
def module_level_function(param1, param2=None, *args, **kwargs):
"""
...
Args:
param1 (int): The first parameter.
param2 (Optional[str]): The second parameter. Defaults to None.
Second line of description should be indented.
*args: Variable length argument list.
**kwargs: Arbitrary keyword arguments.
Ben ediyorum önermek anlatım için aşağıdaki çözümü:
"""
Args:
param1 (int): The first parameter.
param2 (Optional[str]): The second parameter. Defaults to None.
Second line of description should be indented.
*param3 (int): description
*param4 (str):
...
**key1 (int): description
**key2 (int): description
...
Argümanlar Optionaliçin nasıl gerekli olmadığına dikkat edin **key.
Aksi takdirde , * bağımsız değişkenleri altında Other Parametersve **kwargsaltında açıkça listelemeyi deneyebilirsiniz Keyword Args(ayrıştırılmış bölümlere bakın ):
"""
Args:
param1 (int): The first parameter.
param2 (Optional[str]): The second parameter. Defaults to None.
Second line of description should be indented.
Other Parameters:
param3 (int): description
param4 (str):
...
Keyword Args:
key1 (int): description
key2 (int): description
...
Belgelerinde Sphinx için bir doctstring örneği var . Özellikle şunları gösterirler:
def public_fn_with_googley_docstring(name, state=None):
"""This function does something.
Args:
name (str): The name to use.
Kwargs:
state (bool): Current state to be in.
Returns:
int. The return code::
0 -- Success!
1 -- No good.
2 -- Try again.
Raises:
AttributeError, KeyError
A really great idea. A way you might use me is
>>> print public_fn_with_googley_docstring(name='foo', state=None)
0
BTW, this always returns 0. **NEVER** use with :class:`MyPublicClass`.
"""
return 0
Hakkında sormuş olmana rağmen sfenksaçıkça, Google Python Stil Kılavuzu'na da işaret edeceğim . Docstring örnekleri, özellikle kwarg'ları çağırmadıklarını ima ediyor gibi görünüyor. (other_silly_variable = Yok)
def fetch_bigtable_rows(big_table, keys, other_silly_variable=None):
"""Fetches rows from a Bigtable.
Retrieves rows pertaining to the given keys from the Table instance
represented by big_table. Silly things may happen if
other_silly_variable is not None.
Args:
big_table: An open Bigtable Table instance.
keys: A sequence of strings representing the key of each table row
to fetch.
other_silly_variable: Another optional variable, that has a much
longer name than the other args, and which does nothing.
Returns:
A dict mapping keys to the corresponding table row data
fetched. Each row is represented as a tuple of strings. For
example:
{'Serak': ('Rigel VII', 'Preparer'),
'Zim': ('Irk', 'Invader'),
'Lrrr': ('Omicron Persei 8', 'Emperor')}
If a key from the keys argument is missing from the dictionary,
then that row was not found in the table.
Raises:
IOError: An error occurred accessing the bigtable.Table object.
"""
pass
ABB'nin, alt süreç yönetimi belgelerine referans verme ile ilgili kabul edilen yanıta ilişkin bir sorusu vardır. Bir modülü içe aktarırsanız, modül belgelerini inspect.getsource aracılığıyla hızlı bir şekilde görebilirsiniz.
Silent Ghost'un önerisini kullanan python yorumlayıcısından bir örnek:
>>> import subprocess
>>> import inspect
>>> import print inspect.getsource(subprocess)
Elbette yardım işlevi aracılığıyla modül belgelerini de görüntüleyebilirsiniz. Örneğin yardım (alt süreç)
Örnek olarak kwargs için alt işlem dokümantasyonunun hayranı değilim, ancak Google örneğinde olduğu gibi, Sphinx dokümantasyon örneğinde gösterildiği gibi kwargları ayrı ayrı listelemiyor.
def call(*popenargs, **kwargs):
"""Run command with arguments. Wait for command to complete, then
return the returncode attribute.
The arguments are the same as for the Popen constructor. Example:
retcode = call(["ls", "-l"])
"""
return Popen(*popenargs, **kwargs).wait()
Bu yanıtı ABB'nin sorusuna ekliyorum çünkü kodunuzu yorumlamak için içgörüler ve ilham almak için herhangi bir modülün kaynağını veya belgelerini bu şekilde inceleyebileceğinizi belirtmek gerekir.
other_silly_variablebir kwargs argümanı değil, tamamen normal bir argümandır.
Başka biri geçerli bir sözdizimi arıyorsa .. İşte örnek bir docstring. Ben de öyle yaptım, umarım sizin için yararlıdır, ancak özellikle herhangi bir şeyle uyumlu olduğunu iddia edemem.
def bar(x=True, y=False):
"""
Just some silly bar function.
:Parameters:
- `x` (`bool`) - dummy description for x
- `y` (`string`) - dummy description for y
:return: (`string`) concatenation of x and y.
"""
return str(x) + y
def foo (a, b, **kwargs):
"""
Do foo on a, b and some other objects.
:Parameters:
- `a` (`int`) - A number.
- `b` (`int`, `string`) - Another number, or maybe a string.
- `\**kwargs` - remaining keyword arguments are passed to `bar`
:return: Success
:rtype: `bool`
"""
return len(str(a) + str(b) + bar(**kwargs)) > 20
Bu kullandığınız belgelerin tarzına bağlıdır, ancak kullanıyorsanız numpydoc tarzı o belgelemek için tavsiye edilir **kwargskullanarak Other Parameters.
Örneğin, quornian örneğini takip ederek:
def some_function(first, second="two", **kwargs):
"""Fetches and returns this thing
Parameters
----------
first : `int`
The first parameter
second : `str`, optional
The second parameter
Other Parameters
----------------
extra : `list`, optional
Extra stuff. Default ``[]``.
suplement : `dict`, optional
Additional content. Default ``{'key' : 42}``.
"""
Özellikle kwargs varsayılanlarını vermenin tavsiye edildiğine dikkat edin, çünkü bunlar fonksiyon imzasından anlaşılamaz.
Bunu numpydoc tarzında nasıl yapacağınızı arıyorsanız , sfenks uzantısı napolean'daki numpydoc örneğinde ve pandas dokümantasyon sprint 2018'deki docstring kılavuzunda gösterildiği gibi, türü belirtmeden Parametreler bölümünde bahsedebilirsiniz**kwargs .
İşte LSST geliştirici kılavuzundan bulduğum ve parametrenin açıklamasının ne olması gerektiğini çok iyi açıklayan bir örnek **kwargs:
def demoFunction(namedArg, *args, flag=False, **kwargs):
"""Demonstrate documentation for additional keyword and
positional arguments.
Parameters
----------
namedArg : `str`
A named argument that is documented like always.
*args : `str`
Additional names.
Notice how the type is singular since the user is expected to pass individual
`str` arguments, even though the function itself sees ``args`` as an iterable
of `str` objects).
flag : `bool`
A regular keyword argument.
**kwargs
Additional keyword arguments passed to `otherApi`.
Usually kwargs are used to pass parameters to other functions and
methods. If that is the case, be sure to mention (and link) the
API or APIs that receive the keyword arguments.
If kwargs are being used to generate a `dict`, use the description to
document the use of the keys and the types of the values.
"""
Alternatif olarak, @Jonas Adler'in önerdiklerine dayanarak , **kwargsve açıklamasını Other Parametersbölüme koymayı daha iyi buluyorum - matplotlib dokümantasyon kılavuzundaki bu örnek bile aynı şeyi öneriyor.