Структурированный Python Docstrings, IDE-дружелюбный

StackOverflow https://stackoverflow.com/questions/4536437

  •  13-10-2019
  •  | 
  •  

Вопрос

В PHP я использовался для синтаксиса PHPDOC:

/** Do something useful
@param first    Primary data
@return int
@throws BadException
*/
function($first){ ...

-своего рода короткая полезная ссылка: очень удобно, когда все, что вам нужно,-это просто вспомнить «что это?», Особенно для 3-й стороны библиотеки. Кроме того, все IDE могут отображать это во всплывающих подсказках.

Кажется, что в Python нет конвенций: просто простой текст. Это хорошо описывает вещи, но это слишком долго, чтобы быть дайджестом.

ОК, пусть будет. Но в своих приложениях я не хочу использовать груды ясенного текста.

Есть ли хорошо известные конвенции? А как документировать атрибуты класса?! Pycharm Ide Рецепты особенно приветствуются :)

В Python3 есть PEP 3107 Для функциональных аннотаций. Это не полезно для 2.x (2.6, в частности)

Также есть PEP 0287 Для реструктурированного текста: фантазий, но все еще не структурирован.

Это было полезно?

Решение

А Numpydoc Стандарт четко определен, на основе реструктурированного текста (который является стандартным в экосистеме Python) и имеет интеграцию Sphinx. Это должно быть относительно простым, чтобы написать плагин для Pycharm, который может переваривать Numpydoc.

SPHINX также имеет ссылки о том, как документировать атрибуты: http://sphinx.pocoo.org/ext/autodoc.html?highlight=autoattribute

Другие советы

я использую Epydoc. Анкет Он поддерживает комментарии в реструктурированном тексте и генерирует HTML -документацию из этих комментариев (сродни Javadoc).

Лицензировано под: CC-BY-SA с атрибуция
Не связан с StackOverflow
scroll top