Хорошая документация о том, как работает ваше приложение для машинного обучения, почти так же важна, как и само приложение, другие инженеры или ученые должны понимать, как оно работает, чтобы использовать его.

Сегодня я не буду говорить о том, как написать отличную документацию для вашей высокопроизводительной модели. Вместо этого я дам вам несколько советов, как быстро создать потрясающую документацию для вашего проекта, смешав два моих любимых фреймворка/инструмента: 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/