из докстринг надо хранить упорядоченно в файле help.md, который бы в итоге компилировался в нормальную такую человекочитаемую документацию.
а в чем проблема компилировать доку сфинксом сейчас?
В том, что я предлагаю наоборот. Мы делаем упорядоченную доку, а докстринги IDE привязыает в функцию из этой доки .
и получаем два источника правды
сфикс это и так умеет, но не факт что IDE умеют дергать документацию из документации сфинкса.
Нет, мы не пишем докстринги в py файлах вообще. Вместо этого мы используем кавычки для многострочных комментариев.
Я тебе что говорил про троллинг?
Тут прямо в том же файле регулярно кто-нибудь забывает докстринг обновить. Прикинь как это будет весело, если оно размазано по нескольким источникам, и только определённые IDE костылями (плагинами) объединяет всё это в кучу. В чём профит?
Сотрудник становится незаменим
Поэтому нужно в докстрингах писать ещё и доктесты, и покрытие считать, чтобы не забывали их добавлять
Ну, тесты всё-таки отдельный вид деятельности. Хотя такой подход иногда и применялся, с ним есть проблема — тестов дофига, они загромождают код и при этом напрямую с кодом не особо сильно связаны. Можно б было уложить все тесты в экран — можно было бы так и делать.
Обсуждают сегодня