Этот короткий пост смотрит на PDOC , легкая документация Генератор для Python Programs приведен пример, используемый на странице Docs Logline, и исследует некоторые преимущества Automatic DocGen для прагматического программиста.
Радикальная простота
PDOC является супер простым инструментом для документации по программе Python.
Python Package PDOC Предоставляет типы, функции и интерфейс командной строки для доступа к публичной документации модулей Python и для представления его в удобном для пользователя, отраслевом открытом формате. Он лучше всего подходит для проектов мелкого и среднего размера с аккуратными иерархическими API.
Это Pip Пакет, поэтому простая установка командной строки заставит вас работать и работать за считанные секунды. PDOC является легкой альтернативой Sphinx с минимальными когнитивными накладными расходами. Если ты любишь Markdown Вы, наверное, полюбите PDOC . И если вам это не понравится, вам это понравится.
Меньше – больше
Вы можете вывести свою документацию в формате PDF или HTML с простым флагом:
pdoc --PDFpdoc --HTML
Опция PDF является личным фаворитом, потому что он производит хороший Латекс Документ, который заставит Дональда Кнута улыбнуться. Вы даже можете подтолкнуть его к arxiv И притворяйся, что ты физик.
Автогенерированная документация не является платоническим идеалом грамотное программирование , но если у вас есть хорошо выполненные модули, функции и классы, PDOC создает удобный для пользователя разбивка вашего кода в чистые, модульные подзаголовки.
Игра AKQ
Игра Ace-King-Queen-это игрушечная модель в покер, написанную на Python. Вы можете проверить Github Repo здесь Анкет Это игра командной строки, которая содержит сущность ручных диапазонов, частоты блеза и частоты вызовов в мультяшной игре с тремя картами для двух игроков. Эта реализация связывает человеческого игрока против Искусственно умный компьютерный проигрыватель.
Я использовал PDOC Автогенерация HTML Документация для игры Анкет Несколько изменений, и было полезно опубликовать на logline Веб-сайт.
Эффект обзора
За Википедия :
Эффект обзора является когнитивным сдвигом в осознании, о котором сообщают некоторые астронавты во время космического полета, часто при просмотре Земли из космоса.
На более обыденном плоскости проверка вашего кода на высоком уровне может быть проясните, где вы осматриваете атомные элементы сценария, аккуратно расположенного и индексированного. Красота PDOC насколько легким и быстрым он делает процесс DocGen. Вы можете использовать его как часть итеративного рабочего процесса по разработке-чтобы воспринимать периодический взгляд на ваш код с птичьим полетом и обследовать общую картину.
Функциональная проверка программы имеет большой смысл. Если все имена функций и Docstrings проходят тест на запах после быстрого пробега через PDOC , вы, вероятно, на правильном пути. В противном случае это может помочь отсеять неисправную логику или потенциальные ошибки, прежде чем они саботируют ваш сценарий.
Оригинал: “https://dev.to/leemthompo/pdoc-auto-generated-python-documentation-2ndj”