Как удобно разместить актуальную документацию ящика?

Я недавно опубликовал свой первый ящик на crates.io, и мне интересно, смогу ли я поддерживать его документацию проще.

Довольно много документов ящиков размещено на страницах GitHub, поэтому я подумал, что смогу это сделать. Я создал репозиторий user.github.io, сгенерировал документы с cargo doc и подтолкнул их к этому. Все работало просто отлично, документы можно посмотреть с crates.io.

Однако их обновление неудобно; если я изменю документацию ящика, мне нужно:

  1. протолкнуть эти изменения в репо ящика
  2. создавать обновленные документы с помощью cargo doc
  3. переместите файлы документов в папку на странице GitHub
  4. подтолкнуть документы к репо документации

Я уверен, что я делаю это неправильно - особенно пункт 3. Что я могу сделать, чтобы упростить этот процесс? Есть ли лучший способ?

Источник

1 ответ

Решение

Docs.rs является хорошим решением для многих ящиков. Он описывает себя как:

Docs.rs (ранее cratesfyi) - проект с открытым исходным кодом, на котором размещается документация ящиков для языка программирования Rust.

Docs.rs автоматически создает документацию крейтов, выпущенную на crates.io, используя ночной выпуск компилятора Rust.

Это имеет компромиссы:

  • Документация автоматически генерируется и размещается для вас, вам даже не нужно регистрироваться.
  • Документация для каждой версии вашего ящика доступна.
  • Если у вас есть условная компиляция для конкретной платформы, может быть показана документация для разных платформ.
  • Только выпущенные версии ваших ящиков будут документированы. Вы не можете опубликовать опечатку в документации без нового выпуска.
  • Вы обязаны стороннему лицу продолжать предоставлять эту услугу.
  • Вы не можете (в настоящее время?) Контролировать, какие флаги функций используются.

Некоторые люди предпочитают больше контролировать свою документацию или не попадают в целевую аудиторию Docs.rs. Многие из этих случаев предпочитают конфигурировать свою инфраструктуру CI, чтобы генерировать документацию и куда-то выдвигать результат.

Распространенной реализацией этого является использование Travis CI и GitHub Pages, так как многие проекты уже используют эти сервисы. Можно использовать любую систему CI и хостинг HTML, если вам удобно соединять их.

Общая концепция:

  1. Добавьте шаг для создания документации в CI.
  2. При обнаружении определенного типа сборки отправьте сгенерированную документацию на хостинг.
    • Возможные варианты для типа сборки: любая ветка; мастер ветка; тег; и т.п.
    • Будьте осторожны, чтобы не подвергать никаким учетным данным. Распространенной ошибкой (которую я сделал сам) является использование такой команды, как git push https://${GH_TOKEN}@github.com/..., Если эта команда не выполняется, токен печатается в stderr, открывая его для всего мира. Другие менее очевидные случаи также выставляют токен при неудаче, поэтому проверьте его тщательно.

Некоторые люди публикуют сообщения в блогах, подробно описывающие их настройку. Я не проверял, что все это вменяемое, но они могут содержать детали, которые помогут вам настроить конкретное решение.

Источник
Другие вопросы по тегам