У меня есть модуль, содержащий несколько глобальных функций и глобальную переменную.Переменная и некоторые функции следуют «частному» соглашению об именах для Python, с основным подчеркиванием для имени.Другие функции должны быть общедоступными и не иметь начального подчеркивания.
Я объявил __all__ со списком имен своих открытых функций в начале моего файла.
При попытке сгенерировать документацию для этого модуля с использованием epydoc , epydoc рассматривает все в модуле как частное.И, поскольку я использую флаг --no-private, это означает, что в выходных данных отображается только документация по самому модулю, а не элементы модуля или их отдельная документация.
Если я не используюфлаг --no-private с epydoc, все документируется.Но я не хочу личных вещей там.Вот кикер: Если я закомментирую свой __all__, epydoc правильно документирует только открытые элементы моего модуля.
Я относительный новичок в Python, но, насколько я понимаю,__all__ предназначен для того, чтобы избежать неприятностей, когда вы импортируете другие модули, а затем другие модули импортируют ваши, и для того, чтобы пытаться держать в узких местах вещи, когда все технически публично, если вы знаетеназвание того, что вы пытаетесь получить доступ.Пропуск __all__ может привести к плохим вещам ™, или так мне сказали.В то же время, epydoc утверждает, что он и вправо __all__ принимают решение о том, что является публичным, а что нет.
Это то, что я использую epydoc неправильно, неправильно предполагая использование __all__ в моем коде или ошибка в epydoc?(Я уже исправил одну ошибку обработки ошибок в epydoc, которая, вероятно, вызвана более новыми версиями documenttils.)