Scaladoc

静态文档

此文档页面特定于 Scala 3，可能涵盖 Scala 2 中不可用的新概念。除非另有说明，此页面中的所有代码示例均假定你正在使用 Scala 3。

Scaladoc 可以生成静态站点，这些站点来自 Jekyll 或 Docusaurus。拥有一个组合工具可以提供静态文档和 API 之间的交互，从而使两者自然地融合在一起。

创建一个站点与在 Jekyll 中一样简单。站点根目录包含站点的布局，放置在那里的所有文件都将被视为静态文件，或处理模板扩展。

考虑用于模板扩展的文件必须以 *.{html,md} 结尾，并且从现在开始将被称为“模板文件”或“模板”。

一个简单的“hello world”站点可能看起来像这样

.
└── <site-root>/
    └── _docs/
        ├── index.html
        └── getting-started.html

这将为你提供一个站点，其中包含生成文档中的以下文件

index.html
getting-started.html

Scaladoc 可以转换文件和目录（将文档组织成树形结构）。默认情况下，目录的标题基于文件名，内容为空。可以通过在专用目录中创建 index.html 或 index.md（不能同时创建）为每个部分提供索引页面。

在生成静态网站之前，需要在文档 scalacOptions 中设置 -siteroot 值。此值是保存文档的目录。生成的文档的根 URL 也将是 <site-root>。

例如，如果你有一个名为 docs 的目录，并且希望将其视为网站根目录

.
└── docs/
    └── _docs/
        ├── index.html
        └── getting-started.html

那么配置如下

Compile / doc / scalacOptions ++= Seq("-siteroot", "docs")

请记住，使用本地服务器（例如，如果你的输出目录是 output，则可以通过执行以下操作并打开 localhost:8080 来查看具有其提供的所有功能（例如搜索或代码片段）的本地网站。

cd output
python3 -m http.server 8080

属性

Scaladoc 使用 Liquid 模板引擎，并提供针对 Scala 文档的多个自定义过滤器和标签。

可以使用双花括号（例如 ``）访问以下项目相关变量：

projectTitle 使用 -project 标志定义的项目标题。
projectVersion 使用 -project-version 标志定义的项目版本。

在 Scaladoc 中，所有模板都可以包含 YAML 前置内容。前置内容将被解析并放入模板中可通过 Liquid 访问的 page 变量中。

前置内容示例

---
title: My custom title
---

Scaladoc 使用一些预定义属性来控制页面的某些方面。

预定义属性

title 提供将在导航和 HTML 元数据中使用的页面标题。
extraCss 将包含在此页面中的其他 .css 文件。路径应相对于文档根目录。此设置不会导出到模板引擎。
extraJs 将包含在此页面中的其他 .js 文件。路径应相对于文档根目录。此设置不会导出到模板引擎。
hasFrame 设置为 false 时，页面将不包含默认布局（导航、面包屑等），而仅包含令牌 HTML 包装器以提供元数据和资源（js 和 css 文件）。此设置不会导出到模板引擎。
layout - 使用预定义的布局，见下文。此设置不会导出到模板引擎。

重定向属性

除了预定义的属性，Scaladoc 还支持重定向属性，允许你从一个页面重定向到另一个页面。当你将页面移动到新位置但希望旧 URL 继续工作时，这可能很有用。

redirectFrom - 指定你希望从中重定向的 URL。通过使用 redirectFrom 属性，Scaladoc 在指定 URL 生成一个空页面，其中包括到新位置的基于浏览器的重定向。

示例

---
redirectFrom: /absolute/path/to/old/url.html
---

在上述示例中，如果你将页面从 /absolute/path/to/old/url.html 移动到新位置，你可以使用 redirectFrom 确保旧 URL 仍然重定向到新位置。

请注意，redirectFrom 属性的灵感来自名为 jekyll-redirect-from 的 Jekyll 插件。

redirectTo - 指定你希望重定向到的 URL。当你希望重定向到外部页面或无法使用 redirectFrom 时，此属性很有用。

示例

---
redirectTo: https://docs.scala-lang.org.cn/
---

在上述示例中，页面将重定向到 https://docs.scala-lang.org.cn/。

使用现有模板和布局

为了执行模板扩展，Dottydoc 查看 front-matter 中的 layout 字段。以下是模板系统实际应用的一个简单示例，index.html

---
layout: main
---

<h1>Hello world!</h1>

使用像这样的简单主模板

<html>
    <head>
        <title>Hello, world!</title>
    </head>
    <body>
        {{ content }}
    </body>
</html>

将导致 {{ content }} 被 index.html 文件中的 <h1>Hello world!</h1> 替换。

布局必须放在站点根目录中的 _layouts 目录中

├── _layouts
│   └── main.html
└── _docs
    ├── getting-started.md
    └── index.html

资产

为了在静态网站中呈现资产，需要将它们放置在网站根目录中的 _assets 目录中

├── _assets
│   └── images
│        └── myimage.png
└── _docs
    └── getting-started.md

要在页面上引用资产，需要创建一个相对于 _assets 目录的链接

Take a look at the following image: [My image](images/myimage.png)

默认情况下，Scaladoc 会反映呈现网站中 _docs 目录中的目录结构。还可以通过在网站根目录中提供 sidebar.yml 文件来覆盖它。YAML 配置文件描述了呈现的静态网站的结构和目录

index: index.html
subsection:
    - title: Usage
      index: usage/index.html
      directory: usage
      subsection:
        - title: Dottydoc
          page: usage/dottydoc.html
          hidden: false
        - title: sbt-projects
          page: usage/sbt-projects.html
          hidden: false

根元素需要是 subsection。嵌套子部分将导致导航的树状结构。

subsection 属性是

title - 可选字符串 - 子部分的默认标题。前端标题具有更高的优先级。
index - 可选字符串 - 子部分的索引页面的路径。路径相对于 _docs 目录。
directory - 可选字符串 - 将在生成的网站中包含子部分的目录的名称。默认情况下，目录名称是转换为 kebab case 的子部分名称。
subsection - subsection 或 page 的数组。

必须定义 index 或 subsection。使用 index 定义且不使用 subsection 定义的子部分将包含从索引页面的目录中递归加载的页面和目录。

page 属性是

title - 可选字符串 - 页面的默认标题。前端标题具有更高的优先级。
page - 字符串 - 相对于 _docs 目录的页面的路径。
hidden - 可选布尔值 - 指示页面是否应在导航侧边栏中可见的标志。默认情况下，它设置为 false。

注意：YAML 配置文件中的所有路径均相对于 <static-root>/_docs。

标题层次结构

如果多次指定标题，则优先级如下（从最高到最低优先级）

页面

title 来自 markdown/html 文件的 front-matter
title 属性来自 sidebar.yml 属性
文件名

子部分

title 来自 markdown/html 索引文件的 front-matter
title 属性来自 sidebar.yml 属性
文件名

请注意，如果您在树结构中跳过 index 文件，或者您没有在 frontmatter 中指定 title，则将给出通用名称 index。在使用 sidebar.yml 但没有指定 title 或 index，而只指定子部分时，也是如此。同样，将出现通用 index 名称。

博客

博客功能在单独的文档中进行了描述

高级配置

站点根目录的完整结构

.
└── <site-root>/
    ├── _layouts/
    │   └── ...
    ├── _docs/
    │   └── ...
    ├── _blog/
    │   ├── index.md
    │   └── _posts/
    │       └── ...
    └── _assets/
        ├── js/
        │   └── ...
        ├── img/
        │   └── ...
        └── ...

它产生一个静态站点，其中包含文档和博客。它还包含自定义布局和资产。呈现的文档的结构可以基于文件系统，但也可以通过 YAML 配置进行覆盖。

映射目录结构

使用 YAML 配置文件，我们可以定义如何将源目录结构转换为输出目录结构。

查看以下子部分定义

- title: Some other subsection
  index: abc/index.html
  directory: custom-directory
  subsection:
    - page: abc2/page1.md
    - page: foo/page2.md

此小节展示了 YAML 配置映射目录结构的能力。即使索引页和所有定义的子项位于不同的目录中，它们也会呈现在 custom-directory 中。源页 abc/index.html 将生成页 custom-directory/index.html，源页 abc2/page1.md 将生成页 custom-directory/page1.html，源页 foo/page2.md 将生成页 custom-directory/page2.html。

← 上一个 下一个 →