Хорошая документация о том, как работает ваше приложение для машинного обучения, почти так же важна, как и само приложение, другие инженеры или ученые должны понимать, как оно работает, чтобы использовать его.
Сегодня я не буду говорить о том, как написать отличную документацию для вашей высокопроизводительной модели. Вместо этого я дам вам несколько советов, как быстро создать потрясающую документацию для вашего проекта, смешав два моих любимых фреймворка/инструмента: FastAPI (https://fastapi.tiangolo.com/) и MkDocs (https http://www.mkdocs.org/).
МКдокс
MkDocs — очень популярный генератор статических сайтов для документации. Они описывают это как:
MkDocs — это быстрый, простой и совершенно великолепный генератор статических сайтов, предназначенный для создания проектной документации. Исходные файлы документации записываются в формате Markdown и настраиваются с помощью одного файла конфигурации YAML.
Здесь он будет объединен с Material for MkDocs для создания действительно красивой документации: (https://squidfunk.github.io/mkdocs-material/).
Давайте начнем!
Установка и первые шаги
После того, как вы установили Python (обычно pip устанавливается автоматически в зависимости от версии), выполните следующую команду из командной строки:
pip install mkdocs-material
Это автоматически установит совместимые версии всех зависимостей: MkDocs, Markdown, Pygments и Python Markdown Extensions. Материалы для MkDocs всегда стремятся поддерживать последние версии, поэтому нет необходимости устанавливать эти пакеты отдельно.
Далее нам нужно создать новый проект:
mkdocs new medium-app-documentation
В каталоге medium-app-documentation у вас будет:
. ├─ docs/ │ └─ index.md └─ mkdocs.yml
- Один файл конфигурации с именем
mkdocs.yml
- Папка с именем docs, которая будет содержать исходные файлы вашей документации (docs — это значение по умолчанию для параметра конфигурации docs_dir). Сейчас папка docs содержит только одну страницу документации с именем
index.md
.
Наконец, чтобы включить тему «Материалы для MkDocs», добавьте следующие строки в mkdocs.yml
:
theme: name: material
MkDocs поставляется со встроенным сервером разработки, который позволяет вам предварительно просматривать документацию во время работы над ней. Убедитесь, что вы находитесь в том же каталоге, что и файл конфигурации mkdocs.yml
, а затем запустите сервер, выполнив команду mkdocs serve
. Затем посетите:
http://127.0.0.1:8000/
Сервер разработки также поддерживает автоматическую перезагрузку и будет перестраивать вашу документацию всякий раз, когда что-либо изменяется в файле конфигурации, каталоге документации или каталоге темы.
Теперь вы готовы начать писать свой превосходный контент! Откройте файл index.md
в своем любимом редакторе и начните печатать с использованием синтаксиса Markdown (https://en.wikipedia.org/wiki/Markdown, https://www.markdownguide.org/).
Конфигурация
Почти все аспекты настраиваются или модифицируются, ниже мы рассмотрим некоторые из них, для дополнительной настройки (например, добавления дополнительных страниц: https://www.mkdocs.org/getting-started/#adding-pages) посетите соответствующий официальный документация.
- Измените имя сайта: отредактируйте файл конфигурации
mkdocs.yml
, изменив настройку site_name на Medium Article Example и сохраните изменения.
- Изменить URL-адрес сайта: если окончательное местоположение известно, вы можете изменить параметр, указав на него, изменив параметр site_url в файле конфигурации
mkdocs.yml
. Просто не забудьте отредактировать его, прежде чем развертывать свой сайт на рабочем сервере. - Замените значок значка: просто создайте подкаталог img в каталоге docs и скопируйте свой собственный файл
favicon.ico
в этот каталог. MkDocs автоматически обнаружит этот файл и будет использовать его в качестве значка фавикона. - Изменение логотипа: его можно заменить на предоставленное пользователем изображение (любого типа, включая
*.png
и*.svg
), расположенное в папке docs, или на любую иконку, поставляемую в комплекте с темой. Добавьте следующие строки вmkdocs.yml
:
theme: logo: assets/logo.png
- Измените основной цвет: он используется для шапки, сайдбара, текстовых ссылок и ряда других компонентов. Чтобы изменить основной цвет, установите следующее значение в
mkdocs.yml
на допустимое имя цвета:
theme: palette: primary: lime
Интеграция FastAPI
Я большой поклонник того, что создают Себастьян Рамирес и его команда, поэтому я не буду высказывать свое предвзятое мнение 😁. Ниже вы можете найти описание фреймворка в соответствии с официальной документацией FastAPI:
FastAPI — это современная, быстрая (высокопроизводительная) веб-инфраструктура для создания API-интерфейсов с Python 3.6+ на основе стандартных подсказок типов Python.
Ключевые особенности:
- Быстро: очень высокая производительность, на уровне NodeJS и Go (благодаря Starlette и Pydantic). Один из самых быстрых доступных фреймворков Python.
– Быстрое кодирование: увеличьте скорость разработки функций примерно на 200–300 %. *
– Меньше ошибок: сокращение примерно на 40 % ошибок, вызванных человеческим фактором (разработчиком). *
- Интуитивно понятный: отличная поддержка редактора. Завершение везде. Меньше времени на отладку.
– Простота. Разработана так, чтобы ее было легко использовать и осваивать. Меньше времени на чтение документов.
– Кратко: сведите к минимуму дублирование кода. Несколько функций из каждого объявления параметра. Меньше ошибок.
– Надежность: получите готовый к работе код. С автоматической интерактивной документацией.
– Основанный на стандартах: основан на (и полностью совместим) с открытыми стандартами для API: OpenAPI (ранее известный как Swagger) и JSON Schema.
Отсюда я предполагаю, что вы реализовали свое приложение машинного обучения с помощью FastAPI и знаете, как оно работает. Добавить к нему документацию MkDocs очень просто.
Создание вашего сайта
Когда вы закончите редактирование, вы можете создать статический сайт из файлов Markdown с помощью:
mkdocs build
Это создаст каталог site.
Затем в том же каталоге, где находится файл main.py
, создайте папку documentation и вставьте в нее результаты сборки (то, что у вас есть в каталоге сайта: ресурсы, поиск, 404.html и т. д.).
Обновление main.py
Добавьте в скрипт main.py следующее:
from fastapi import FastAPI from fastapi.staticfiles import StaticFiles app = FastAPI() app.mount("/documentation", StaticFiles(directory="/documentation", html=True), name="documentation")
Докер
Если вы развертываете приложение FastAPI с помощью Docker (https://fastapi.tiangolo.com/deployment/docker/), просто измените:
app.mount("/documentation", StaticFiles(directory="/code/app/documentation", html=True), name="documentation")
В этом случае папка documentation находится внутри каталога app.
После развертывания API вы можете получить доступ к документации, добавив /documentation к URL-адресу API:
https://yourapiurl/documentation/