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