Настройки

Language

    В этой главе перечислены параметры конфигурации, которые можно использовать при вызове 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

    Логотип проекта, который появляется в верхнем левом углу. Для темной темы можно выделить отдельный логотип с суффиксом _dark. Например, если есть логотип mylogo.png, то для темной темы предполагается mylogo_dark.png. Чтобы обеспечить совместимость с псевдонимами Scala2 с -doc-logo

    -project-footer

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

    -comment-syntax

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

    -revision

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

    -source-links

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

    Примеры исходных ссылок: -source-links:docs=github://scala/scala3/main#docs

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

    <sub-path>=<source-link>

    где <source-link> является одним из следующих:

    • 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

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

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

    Допустимые значения имеют вид: [github|twitter|gitter|discord]::link. 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. Все остальные пользователи не должны касаться этой настройки.

    ← previous

    Contributors to this page:

    Contents
    Problem with this page?
         Please help us fix it!