Блог Scala Функ. программирование Классы типов Алгоритмы Библиотеки Упражнения Ресурсы

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

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

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

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

Чтобы выполнить расширение шаблона, 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:

Либо index, либо subsection должны быть определены. Подраздел, определенный с index и без subsection, будет содержать страницы и каталоги, загружаемые рекурсивно из каталога индексной страницы.

Свойства page:

Все пути в файле конфигурации YAML относятся к <static-root>/_docs.

Иерархия title

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

Страница

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

Подраздел

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

Обратите внимание, что если пропустить 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.

Ссылки: