Версионность сайта

Scaladoc предоставляет удобный способ переключения между различными версиями документации. Эта функция полезна, если желательно предоставить старые документы пользователям, которые не перешли на новую версию библиотеки.

Как это настроить

Эта функция была разработана для легкой масштабируемости без необходимости повторного создания всех scaladocs после добавления новой версии. Для этого вводится новая настройка: -versions-dictionary-url

. Его аргумент должен быть URL-адресом документа JSON, содержащего информацию о расположении конкретных версий. Файл JSON должен содержать свойство versions

со словарём, связывающий метки определенных версий документации с URL-адресами, указывающими на их index.html

.

Пример JSON-файла:

{
  "versions": {
    "3.0.x": "https://dotty.epfl.ch/3.0.x/docs/index.html",
    "Nightly": "https://dotty.epfl.ch/docs/index.html"
  }
}

Такие документы необходимо указывать для каждой из версий, однако позже это дает больше гибкости. Если необходимо добавить версию документов API рядом с предыдущими 5 версиями, которые уже опубликованы, нужно только загрузить новые документы на веб-сервер и добавить новую запись в файл JSON. Все версии сайта теперь узнают о новой версии.

Важно отметить, что существует только один файл JSON, чтобы избежать избыточности, и каждый scaladoc должен заранее настроить свой URL-адрес, например, в sbt:

doc / scalacOptions ++= Seq("-versions-dictionary-url", "https://dotty.epfl.ch/versions.json")

Как это выглядит с точки зрения пользователя

Предоставление файла JSON через -versions-dictionary-url

позволяет scaladoc связывать версии. Также удобно иметь возможность изменить метку ревизии в выпадающем меню. Все изменится автоматически.

---

Ссылки:

• Scaladoc Guide