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

Language

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

    Имейте в виду, что для локального просмотра вашего сайта со всеми его функциями, такими как поиск или фрагменты, требуется локальный сервер. Например, если ваш выходной каталог - output, вы можете использовать python сервер для просмотра всего, выполнив следующие действия и открыв localhost:8080:

    cd output
python3 -m http.server 8080

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

    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 - предопределенный макет для использования, см. ниже. Этот параметр не экспортируется в механизм шаблонов.

    Свойства перенаправления:

    В дополнение к предустановленным свойствам, Scaladoc также поддерживает свойства перенаправления, которые позволяют вам перенаправлять с одной страницы на другую. Это может быть полезно, когда вы перемещаете страницу на новое место, но хотите, чтобы старый URL-адрес работал.

    • redirectFrom - указывает на URL-адрес, с которого вы хотите выполнить перенаправление. Используя свойство redirectFrom, Scaladoc создает пустую страницу по этому URL-адресу, который включает браузерное перенаправление на текущую страницу.

    Пример:

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

    В приведенном выше примере, если вы перемещаете страницу из /absolute/path/to/old/url.html на новое место, то вы можете использовать redirectFrom, чтобы убедиться, что старый URL-адрес по-прежнему перенаправляет на новое место.

    Обратите внимание, что свойство redirectFrom было вдохновлено плагином Jekyll под названием jekyll-redirect-from.

    • redirectTo — указывает URL-адрес, на который вы хотите перенаправить с текущей страницы. Это свойство полезно, когда вы хотите перенаправить на внешнюю страницу или когда нельзя использовать redirectFrom.

    Пример:

    ---
redirectTo: https://docs3.scala-lang.org/
---

    В приведенном выше примере страница будет перенаправлена на https://docs3.scala-lang.org/.

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

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

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

    Страница

    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.

    ← previous next →

    Contributors to this page:

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