Настройки

В этой главе перечислены параметры конфигурации, которые можно использовать при вызове scaladoc. Некоторую информацию, показанную здесь, можно получить, вызвав scaladoc с флагом -help.

Изменения scaladoc по сравнению со Scala 2

Scaladoc был переписан с нуля, и некоторые функции оказались бесполезными в новом контексте. Текущее состояние совместимости со старыми флагами scaladoc можно увидеть здесь.

Указание настроек

Настройки scaladoc можно указывать в качестве аргументов командной строки, например, scaladoc -d output -project my-project target/scala-3.0.0-RC2/classes. При вызове из sbt, обновите значение Compile / doc / scalacOptions и Compile / doc / target соответственно, например

Compile / doc / target := file("output"),
Compile / doc / scalacOptions ++= Seq("-project", "my-project"),

Обзор всех доступных настроек

-project

Название проекта. Чтобы обеспечить совместимость с псевдонимами Scala2 с -doc-title

-project-version

Текущая версия проекта, которая отображается в верхнем левом углу. Чтобы обеспечить совместимость с псевдонимами Scala2 с -doc-version

-project-logo

Логотип проекта, который появляется в верхнем левом углу. Чтобы обеспечить совместимость с псевдонимами Scala2 с -doc-logo

Строковое сообщение, которое отображается в разделе нижнего колонтитула. Чтобы обеспечить совместимость с псевдонимами Scala2 с -doc-footer

-comment-syntax

Язык стилей, используемый для разбора комментариев. В настоящее время поддерживается два синтаксиса: markdown или wiki. Если настройка отсутствует, по умолчанию - markdown.

-revision

Редакция (ветвь или ссылка), используемая для создания проекта. Полезно с исходными ссылками, чтобы они не всегда указывали на последний мастер, который может быть изменен.

-source-links

Ссылки на источники обеспечивают сопоставление между файлом в документации и репозиторием кода.

Примеры исходных ссылок: -source-links:docs=github://lampepfl/dotty/master#docs

Принимаемые форматы:

<sub-path>=<исходная-ссылка> <исходная-ссылка>

где <ссылка-источник> является одним из следующих:

github://<organization>/<repository>[/revision][#subpath] будет соответствовать https://github.com/$organization/$repository/[blob|edit]/$revision[/$subpath]/$filePath[$lineNumber], если редакция не указана, тогда требуется указать редакцию в качестве аргумента для Scaladoc
gitlab://<organization>/<repository> будет соответствовать https://gitlab.com/$organization/$repository/-/[blob|edit]/$revision[/$subpath]/$filePath[$lineNumber], если редакция не указана, тогда требуется, чтобы редакция была указана как аргумент в Scaladoc
<scaladoc-template>

<scaladoc-template> — это формат параметра doc-source-url из старого scaladoc. ПРИМЕЧАНИЕ. Поддерживаются только шаблоны €{FILE_PATH_EXT}, €{TPL_NAME}, €{FILE_EXT}, €{FILE_PATH} и €{FILE_LINE}.

Шаблон может быть определен только подмножеством источников, определенных префиксом пути, представленным <sub-path>. В этом случае пути, используемые в шаблонах, будут относительными относительно <sub-path>.

-external-mappings

Сопоставление регулярных выражений, соответствующих записям пути к классам, и внешней документации.

Пример внешнего сопоставления:

-external-mappings:.*scala.*::scaladoc3::https://scala-lang.org/api/3.x/,.*java.*::javadoc::https://docs.oracle.com/javase/8/docs/api/

Отображение имеет вид <regex>::[scaladoc3|scaladoc|javadoc]::<path>. Можно указать несколько сопоставлений, разделенных запятыми, как показано в примере.

Ссылки на социальные сети. Например:

-social-links:github::https://github.com/lampepfl/dotty,discord::https://discord.com/invite/scala,twitter::https://twitter.com/scala_lang

Допустимые значения имеют вид: [github|twitter|gitter|discord]::ссылка. Scaladoc также поддерживает custom::link::white_icon_name::black_icon_name. В этом случае иконки должны находиться в каталоге images/.

-skip-by-id

Идентификаторы пакетов или классов верхнего уровня, которые следует пропускать при создании документации.

-skip-by-regex

Регулярные выражения, соответствующие полным именам пакетов или классов верхнего уровня, которые следует пропускать при создании документации.

-doc-root-content

Файл, из которого следует импортировать документацию корневого пакета.

-author

Добавление авторов в строку документации @author Name Surname по умолчанию не будет включено в сгенерированную html-документацию. Если необходимо явно пометить классы авторами, scaladoc запускается с данным флагом.

-groups

Группировка похожих функций вместе (на основе аннотации @group)

-private

Показать все типы и члены. Если параметр не указан, показывать только public и protected типы и члены.

-doc-canonical-base-url

Базовый URL-адрес для использования в качестве префикса и добавления canonical URL-адресов на все страницы. Канонический URL-адрес может использоваться поисковыми системами для выбора URL-адреса, который вы хотите, чтобы люди видели в результатах поиска. Если не установлено, канонические URL-адреса не генерируются.

-siteroot

Каталог, содержащий статические файлы, из которых создается документация. Каталог по умолчанию - ./docs

-no-link-warnings

Подавить предупреждения для двусмысленных или невалидных ссылок. Не влияет на предупреждения о некорректных ссылках ресурсов и т. д.

-versions-dictionary-url

URL-адрес, указывающий на документ JSON, содержащий словарь: version label -> documentation location. Файл 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"
  }
}

-snippet-compiler

Аргументы компилятора сниппета позволяют настроить проверку типа сниппета.

Этот параметр принимает список аргументов в формате: args := arg{,args} arg := [path=]flag, где path - префикс пути к исходным файлам, в которых находятся сниппеты, и flag - режим проверки типов.

Если path отсутствует, аргумент будет использоваться по умолчанию для всех несопоставленных путей.

Доступные флаги:

compile — включает проверку фрагментов.
nocompile — отключает проверку сниппетов.
fail — включает проверку сниппета, утверждает, что сниппет не компилируется.

Флаг fail удобен для фрагментов, которые показывают, что какое-то действие в конечном итоге завершится ошибкой во время компиляции.

Пример использования:

-snippet-compiler:my/path/nc=nocompile,my/path/f=fail,compile

Что значит:

все фрагменты в файлах в каталоге my/path/nc вообще не должны рассматриваться снипеттом
все фрагменты в файлах в каталоге my/path/f не должны компилироваться во время компиляции
все остальные фрагменты должны компилироваться успешно

-scastie-configuration

Определите дополнительную sbt конфигурацию для Scastie фрагментов кода. Например, когда вы импортируете внешние библиотеки в свои фрагменты, необходимо добавить соответствующие зависимости.

"-scastie-configuration", """libraryDependencies += "org.apache.commons" % "commons-lang3" % "3.12.0""""

-Ysnippet-compiler-debug

Установка этого параметра заставляет компилятор сниппета печатать сниппет по мере его компиляции (после упаковки).

-Ydocument-synthetic-types

Включение в документацию страниц с документацией по встроенным типам (например, Any, Nothing). Этот параметр полезен только для stdlib, поскольку scaladoc для Scala 3 использует файлы TASTy. Все остальные пользователи не должны касаться этой настройки.

Ссылки:

Scaladoc Guide