{"draftJsState":{"blocks":[{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"","type":"unstyled","key":"fmaoc"},{"data":{"image":{"id":"5f0825c7ce7e5e00487f5868"}},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"","type":"atomic:image","key":"f2rch"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Все мы когда-то писали такой код, взглянув на который две недели спустя, трудно было понять почему и как он работает. Нам часто приходится иметь дело с плохо документированным кодом. Но так не должно быть.","type":"unstyled","key":"blo7n"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[{"length":21,"offset":97,"style":"ITALIC"}],"text":"Нельзя недооценивать важность написания читаемого кода, который является синонимом качественного документирования кода. На данный момент в Python нет «идеального» способа написания докстрингов (строк документации), так же как и нет единого стиля, которого можно придерживаться.","type":"unstyled","key":"8so5d"},{"data":{},"depth":0,"entityRanges":[{"key":0,"length":6,"offset":98}],"inlineStyleRanges":[],"text":"Мы объединили наиболее часто употребляемые стили документирования в этой статье и остановились на Sphinx для дальнейшей разработки. Стиль Sphinx является официальным стандартом документации Python, и мы ценим его за простоту использования.","type":"unstyled","key":"18f3i"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Мы надеемся, что эта статья даст вам общее представление о стилях и применениях строк документации, что станет хорошей основой для формирования опрятной документации в вашем коде Python.","type":"unstyled","key":"ai0ro"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[{"length":20,"offset":0,"style":"BOLD"}],"text":"Что такое докстринг?","type":"header-two","key":"56s07"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[{"length":19,"offset":131,"style":"BOLD"}],"text":"Строка документации — это однострочный или многострочный строковый литерал, разделенный тройными одинарными или двойными кавычками \"\"\"\"\"\" в начале модуля, класса, метода или функции, который описывает, что делает функция.","type":"unstyled","key":"cetou"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Только в случае, если это первый оператор в функции, он может быть распознан компилятором байт-кода Python и доступен как атрибуты объекта времени выполнения с помощью метода __doc__ или функции help().","type":"unstyled","key":"f8poq"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"def show_docstring(): \n \"\"\"Print function description to user\"\"\"\n print(\"Using __doc__ method:\")\n print(show_docstring.__doc__)\n\n print(\"Using help() function:\")\n help(show_docstring)\n\n$ show_docstring();\n\"Using __doc__ method:\"\n\"Print function description to user\"\n\"Using help() function:\"\n\"Print function description to user\"","type":"blockquote","key":"3v9d8"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[{"length":15,"offset":0,"style":"BOLD"}],"text":"Лучшие практики","type":"header-three","key":"aadr9"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Все модули, классы, методы и функции, включая конструктор __init__в пакетах, должны иметь строки документации.","type":"unordered-list-item","key":"epbmq"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Описания пишутся с заглавной буквы и включают пунктуацию в конце предложения.","type":"unordered-list-item","key":"7jmpq"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[{"length":27,"offset":87,"style":"BOLD"}],"text":"Всегда окружайте строки документации двойными кавычками по три раза, как показано тут: \"\"\"Triple double quotes.\"\"\".","type":"unordered-list-item","key":"dhkio"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"В конце докстринга пустая строка не ставится. ","type":"unordered-list-item","key":"aq4pk"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[{"length":23,"offset":0,"style":"BOLD"}],"text":"Однострочные докстринги","type":"header-two","key":"3d34m"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"def power(a, b): \n \"\"\"Returns arg1 raised to power arg2.\"\"\"\n return a**b","type":"blockquote","key":"8qhbc"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[{"length":7,"offset":67,"style":"ITALIC"},{"length":26,"offset":103,"style":"BOLD"}],"text":"Однострочный докстринг прописывает функцию или действие метода как команду, а не как описание функции: \"\"\"Do this, return that\"\"\".","type":"unordered-list-item","key":"8aqai"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[{"length":23,"offset":45,"style":"BOLD"}],"text":"Однострочный докстринг не является “подписью” function(a, b) -> list , повторяющей параметры функции/метода.","type":"unordered-list-item","key":"dk0bv"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[{"length":24,"offset":0,"style":"BOLD"}],"text":"Многострочные докстринги","type":"header-two","key":"9584b"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"def suggest_places(auth_key, city):\n \"\"\"Returns longitude and latitude of first suggested location in the Netherlands from Postcode API.\n \n :param auth_key: authorization key for Postcode API\n :type auth_key: str\n :param city: textual input for city names to match in Postcode API\n :type city: str\n \n :rtype: (str, str), str, str\n :return: (longitude, latitude), Postcode API status code, Postcode API error message","type":"blockquote","key":"a8nuv"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Многострочные докстринги содержат те же строковые литералы, что и однострочные, но здесь также присутствует описание параметров функции и возвращаемых значений, которое отделено от строки-команды пустой строкой.","type":"unstyled","key":"f77jn"},{"data":{},"depth":0,"entityRanges":[{"key":1,"length":13,"offset":98},{"key":2,"length":12,"offset":114},{"key":3,"length":12,"offset":180}],"inlineStyleRanges":[],"text":"Различные конвенции кодирования предписывают стили написания многострочных докстрингов, такие как Google Format и NumPy Format, однако самым простым и традиционным стилем является Sphinx style.","type":"unstyled","key":"8rkqp"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[{"length":12,"offset":0,"style":"BOLD"}],"text":"Стиль Sphinx","type":"header-two","key":"4iogm"},{"data":{},"depth":0,"entityRanges":[{"key":4,"length":93,"offset":74}],"inlineStyleRanges":[],"text":"Sphinx является официальным стандартом документирования в Python. Он также по умолчанию используется в популярной интегрированной среде разработки Pycharm от JetBrains. Для этого нужно включить в тройные кавычки определение вашей функции и нажать клавишу Enter. ","type":"unstyled","key":"cn36m"},{"data":{},"depth":0,"entityRanges":[{"key":5,"length":23,"offset":62}],"inlineStyleRanges":[],"text":"Стиль Sphinx использует синтаксис облегченного языка разметки reStructuredText (reST), предназначенного одновременно для:","type":"unstyled","key":"a9h9a"},{"data":{},"depth":0,"entityRanges":[{"key":6,"length":8,"offset":58}],"inlineStyleRanges":[],"text":"Обработки специальным программным обеспечением, таким как Docutils.","type":"unordered-list-item","key":"a1vs9"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Легкого чтения программистами, которые читают и пишут исходный код Python. ","type":"unordered-list-item","key":"3hn40"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"def multiply(a, b, c=0):\n \"\"\"Return sum of multiplication of all arguments.\n \n :param a: arg1\n :type a: int\n :param b: arg2\n :type b: int\n :param c: arg3, defaults to 0\n :type c: int, optional\n\n :raises ValueError: if arg1 is equal to arg2\n \n :rtype: int\n :return: multiplication of all arguments \n \"\"\"\n if a == b:\n raise ValueError('arg1 must not be equal to arg2')\n\n return a*b*c","type":"blockquote","key":"ak028"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[{"length":16,"offset":0,"style":"BOLD"}],"text":"Синтаксис Sphinx","type":"header-three","key":"9055i"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[{"length":23,"offset":86,"style":"BOLD"}],"text":"В Sphinx используется такой же, как и в большинстве языков программирования синтаксис: keyword(reserved word). Наиболее важные ключевые слова:","type":"unstyled","key":"2ilss"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[{"length":5,"offset":0,"style":"BOLD"},{"length":4,"offset":8,"style":"BOLD"}],"text":"param и type: значение параметра и тип его переменной;","type":"unordered-list-item","key":"3lrhb"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[{"length":7,"offset":0,"style":"BOLD"},{"length":5,"offset":9,"style":"BOLD"}],"text":"return и rtype: возвращаемое значение и его тип;","type":"unordered-list-item","key":"dshf5"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[{"length":7,"offset":0,"style":"BOLD"}],"text":":raises: описывает любые ошибки, которые возникают в коде;","type":"unordered-list-item","key":"6oclt"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[{"length":12,"offset":0,"style":"BOLD"}],"text":".. seealso:: : информация для дальнейшего чтения;","type":"unordered-list-item","key":"bqk96"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[{"length":10,"offset":0,"style":"BOLD"}],"text":".. notes:: : добавление заметки;","type":"unordered-list-item","key":"6vvcl"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[{"length":13,"offset":0,"style":"BOLD"},{"length":1,"offset":14,"style":"BOLD"}],"text":".. warning:: : добавление предупреждения.","type":"unordered-list-item","key":"e48l2"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[{"length":7,"offset":152,"style":"BOLD"},{"length":6,"offset":161,"style":"BOLD"},{"length":8,"offset":169,"style":"BOLD"}],"text":"Хотя порядок этих ключевых слов не является фиксированным, (опять же) принято придерживаться вышеуказанного порядка на протяжении всего проекта. Записи seealso, notes и warning не являются обязательными.","type":"unstyled","key":"7rg09"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[{"length":2,"offset":55,"style":"BOLD"}],"text":"Например, вы можете связывать параметры с помощью знака |, как показано тут:","type":"unstyled","key":"e07vu"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":":param x: An integer, defaults to None\n:type x: int:param y: An integer or string\n\n:param y: An integer or string\n:type y: int|string","type":"blockquote","key":"cgbim"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[{"length":12,"offset":0,"style":"BOLD"}],"text":"Макет Sphynx","type":"header-three","key":"5rsks"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Общий макет этой строки документации показан ниже.","type":"unstyled","key":"dffvi"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"\"\"\"< Summary. >\n\n:param : , defaults to \n:type : (, optional)\n\n\n:raises : \n\n\n:rtype: \n:return: \n\"\"\"","type":"blockquote","key":"cuago"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Вот и все.","type":"unstyled","key":"agcvp"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"Эти стили документирования очень просты в применении, машиночитаемы для встроенных функций, интегрированных сред разработки и строк кода, а также являются единственным способом предоставить отлично документированные и читаемые функции для программистов. Их можно понять даже спустя несколько месяцев.","type":"unstyled","key":"m2gi"},{"data":{},"depth":0,"entityRanges":[],"inlineStyleRanges":[],"text":"","type":"marker","key":"VQ9Iw9eoZBAnZjEkjrUP"}],"entityMap":{"0":{"data":{"href":"https://www.sphinx-doc.org/en/master/","url":"https://www.sphinx-doc.org/en/master/"},"mutability":"MUTABLE","type":"LINK"},"1":{"data":{"url":"https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html"},"mutability":"MUTABLE","type":"LINK"},"2":{"data":{"href":"https://numpydoc.readthedocs.io/en/latest/","url":"https://numpydoc.readthedocs.io/en/latest/"},"mutability":"MUTABLE","type":"LINK"},"3":{"data":{"href":"https://www.sphinx-doc.org/en/master/","url":"https://www.sphinx-doc.org/en/master/"},"mutability":"MUTABLE","type":"LINK"},"4":{"data":{"href":"https://www.jetbrains.com/help/pycharm/creating-documentation-comments.html","url":"https://www.jetbrains.com/help/pycharm/creating-documentation-comments.html"},"mutability":"MUTABLE","type":"LINK"},"5":{"data":{"href":"https://docutils.sourceforge.io/rst.html","url":"https://docutils.sourceforge.io/rst.html"},"mutability":"MUTABLE","type":"LINK"},"6":{"data":{"href":"https://docutils.sourceforge.io/","url":"https://docutils.sourceforge.io/"},"mutability":"MUTABLE","type":"LINK"}}},"mentions":[]}