Что это. Если вы хотите документировать функцию или класс, вы помещаете строку сразу после определения. Например:
def foo():
"""This function does nothing."""
pass
Но как насчет модуля? Как я могу документировать, что делает файл .py?
Что это. Если вы хотите документировать функцию или класс, вы помещаете строку сразу после определения. Например:
def foo():
"""This function does nothing."""
pass
Но как насчет модуля? Как я могу документировать, что делает файл .py?
Для пакетов вы можете документировать его в __init__.py
.
Для модулей вы можете добавить docstring просто в файл модуля.
Вся информация здесь: http://www.python.org/dev/peps/pep-0257/
Добавьте строку документации в качестве первого оператора в модуле.
"""
Your module verbose yet thorough docstring.
"""
import foo
# ...
Для пакетов вы можете добавить свою строку документации в __init__.py
.
Вот пример строки стиля Python Google Style о том, как модуль может быть задокументирован. В основном есть информация о модуле, как его выполнить, а также информация о переменных уровня модуля и список элементов ToDo.
"""Example Google style docstrings.
This module demonstrates documentation as specified by the 'Google
Python Style Guide'_. Docstrings may extend over multiple lines.
Sections are created with a section header and a colon followed by a
block of indented text.
Example:
Examples can be given using either the ''Example'' or ''Examples''
sections. Sections support any reStructuredText formatting, including
literal blocks::
$ python example_google.py
Section breaks are created by resuming unindented text. Section breaks
are also implicitly created anytime a new section starts.
Attributes:
module_level_variable1 (int): Module level variables may be documented in
either the ''Attributes'' section of the module docstring, or in an
inline docstring immediately following the variable.
Either form is acceptable, but the two should not be mixed. Choose
one convention to document module level variables and be consistent
with it.
Todo:
* For module TODOs
* You have to also use ''sphinx.ext.todo'' extension
.. _Google Python Style Guide:
http://google.github.io/styleguide/pyguide.html
"""
module_level_variable1 = 12345
def my_function():
pass
...
...
Вы делаете это точно так же. Поместите строку в качестве первого оператора в модуле.
Легко, вы просто добавляете строку документа в верхней части модуля.
Для пакетов PyPI:
Если вы добавите подобные строки в файл __init__.py, как показано ниже
"""
Please refer to the documentation provided in the README.md,
which can be found at gorpyter PyPI URL: https://pypi.org/project/gorpyter/
"""
# <IMPORT_DEPENDENCIES>
def setup():
"""Verify your Python and R dependencies."""
Затем вы получите это при ежедневном использовании функции справки.
help(<YOUR_PACKAGE>)
DESCRIPTION
Please refer to the documentation provided in the README.md,
which can be found at gorpyter PyPI URL: https://pypi.org/project/gorpyter/
FUNCTIONS
setup()
Verify your Python and R dependencies.
Обратите внимание, что моя помощь DESCRIPTION
вызвана наличием этой первой строки документации в самом верху файла.