Настройка шаблона JSDoc по умолчанию

Содержание

• Генерация отформатированных исходных файлов
• Копирование статических файлов в выходной каталог
• Отображение текущей даты в нижнем колонтитуле страницы
• Отображение полных имен в колонке навигации
• Переопределение файла макета шаблона по умолчанию
• Связанные ссылки

Шаблон JSDoc по умолчанию предоставляет несколько параметров, которые можно использовать для настройки внешнего вида и содержимого сгенерированной документации.

Чтобы использовать эти параметры, необходимо создать файл конфигурации для JSDoc и установить соответствующие параметры в файле конфигурации.

Генерация отформатированных исходных файлов

По умолчанию, шаблон JSDoc по умолчанию генерирует отформатированные версии ваших исходных файлов. Он также создает ссылки на эти отформатированные файлы в документации.

Чтобы отключить отформатированные файлы, установите параметр templates.default.outputSourceFiles в false. Использование этого параметра также удаляет ссылки на ваши исходные файлы из документации. Этот параметр доступен в JSDoc 3.3.0 и более поздних версиях.

Копирование статических файлов в выходной каталог

Шаблон JSDoc по умолчанию автоматически копирует несколько статических файлов, таких как CSS-стили, в выходной каталог. В JSDoc 3.3.0 и более поздних версиях вы можете указать шаблону по умолчанию копировать дополнительные статические файлы в выходной каталог. Например, вы можете скопировать каталог изображений в выходной каталог, чтобы отобразить эти изображения в вашей документации.

Чтобы скопировать дополнительные статические файлы в выходной каталог, используйте следующие параметры:

• templates.default.staticFiles.include: Массив путей, содержимое которых должно быть скопировано в выходной каталог. Подкаталоги также будут скопированы.
• templates.default.staticFiles.exclude: Массив путей, которые не должны быть скопированы в выходной каталог.
• templates.default.staticFiles.includePattern: Регулярное выражение, указывающее, какие файлы следует копировать. Если это свойство не определено, будут скопированы все файлы.
• templates.default.staticFiles.excludePattern: Регулярное выражение, указывающее, какие файлы следует пропустить. Если это свойство не определено, ничего пропускаться не будет.

Чтобы скопировать все статические файлы из ./myproject/static в выходной каталог:

{
  "templates": {
    "default": {
      "staticFiles": {
        "include": [
            "./myproject/static"
        ]
      }
    }
  }
}

Если ваш каталог статических файлов содержит файл ./myproject/static/img/screen.png, вы можете отобразить изображение в своих документах, используя тег HTML <img src="img/screen.png">.

Отображение текущей даты в нижнем колонтитуле страницы

По умолчанию, шаблон JSDoc по умолчанию всегда отображает текущую дату в нижнем колонтитуле сгенерированной документации. В JSDoc 3.3.0 и более поздних версиях вы можете опустить текущую дату, установив параметр templates.default.includeDate в false.

Отображение полных имен в колонке навигации

По умолчанию, шаблон JSDoc по умолчанию отображает сокращенную версию имени каждого символа в колонке навигации. Например, символ my.namespace.MyClass будет отображаться просто как MyClass. Чтобы отобразить полное имя вместо этого, установите параметр templates.default.useLongnameInNav в true. Этот параметр доступен в JSDoc 3.4.0 и более поздних версиях.

Переопределение файла макета шаблона по умолчанию

Шаблон по умолчанию использует файл с именем layout.tmpl для указания заголовка и нижнего колонтитула для каждой страницы в сгенерированной документации. В частности, этот файл определяет, какие файлы CSS и JavaScript загружаются для каждой страницы. В JSDoc 3.3.0 и более поздних версиях вы можете указать свой собственный файл layout.tmpl, что позволит вам загрузить собственные пользовательские файлы CSS и JavaScript в дополнение к стандартным файлам или вместо них.

Чтобы использовать эту функцию, установите параметр templates.default.layoutFile в путь к вашему настроенному файлу макета. Относительные пути разрешаются относительно текущего рабочего каталога; пути к файлу конфигурации; и каталога JSDoc, в этом порядке.

Связанные ссылки

Настройка JSDoc с помощью файла конфигурации