Статическая документация

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 (но не одновременно) в выделенном каталоге.

Характеристики

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

В Scaladoc все шаблоны могут содержать вступительную часть YAML. Передняя часть анализируется и помещается в переменную page

, доступную в шаблонах через Liquid.

Пример вступительной статьи:

---
title: My custom title
---

Scaladoc использует некоторые предопределенные свойства для управления аспектами страницы.

Предустановленные свойства:

title обеспечивает заголовок страницы, который будет использоваться в навигации и метаданных HTML.
extraCss - дополнительные файлы .css, которые будут включены в эту страницу. Пути должны указываться относительно корня документации. Этот параметр не экспортируется в механизм шаблонов.
extraJs - дополнительные файлы .js, которые будут включены в эту страницу. Пути должны указываться относительно корня документации. Этот параметр не экспортируется в механизм шаблонов.
hasFrame - если установлено значение false, страница не будет включать макет по умолчанию (навигацию, breadcrumbs и т.д.), а только токен-оболочку HTML для предоставления метаданных и ресурсов (файлы js и css). Этот параметр не экспортируется в механизм шаблонов.
layout - предопределенный макет для использования, см. ниже. Этот параметр не экспортируется в механизм шаблонов.

Использование существующих шаблонов и макетов

Чтобы выполнить расширение шаблона, Dottydoc просматривает поле layout

во вступительной части. Вот простой пример системы шаблонов в действии index.html:

---
layout: main
---

<h1>Hello world!</h1>

С таким простым основным шаблоном, как этот:

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

content

будет заменен на <h1>Hello world!</h1> в файле index.html.

Макеты должны быть размещены в каталоге _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

Если заголовок указан несколько раз, приоритет будет следующим (от высшего к низшему приоритету):

Страница

title из front-matter файла markdown/html
title свойство из sidebar.yml свойства
имя файла

Подраздел

title из front-matter индексного файла markdown/html
title свойство из sidebar.yml свойства
имя файла

Обратите внимание, что если пропустить index

файл в древовидной структуре или не указать 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.

Ссылки:

Scaladoc Guide

scalabook