По умолчанию "Домашний" текст и содержание для JSDoc

После запуска основной компиляции/рендеринга JSDoc из Node.js:

jsdoc file1.js file2.js

Я получаю хорошо отформатированный документ, используя шаблон по умолчанию внутри каталога "out". Почти все, как ожидалось!

Но при открытии документа он всегда говорит "Главная" на странице index.html, не имеет содержимого на этой начальной странице и имеет "Главная" в навигации на боковой панели.

Как и где я обозначаю название проекта так, чтобы оно заменяло "Главная" ? Я также хотел бы увидеть описание проекта, а также информацию об авторе и авторских правах.

Похоже, что самое главное в JSDoc, но я не могу найти информацию! Я пробовал следующее, основанное на какой-то случайной статье, которую я нашел в Интернете:

/** 
 * This JavaScript file contains foo bar baz...
 * 
 * @projectname Project Name
 * @version 0.1
 * @author Greg Pettit
 * @copyright 2015
 * 
 */

Но у меня нет любви.

[отредактировано для добавления:]

Обнаружена директива @file/@fileOverview/@overview (все синонимы), которая несколько полезна, поскольку теперь я могу описать и установить информацию об авторских правах/авторах для каждого файла:

/** 
 * @file Project description which renders below the individual filename and therefore isn't a real overview blurb.
 * 
 * @version 0.1
 * @author Greg Pettit
 * @copyright 2015
 * 
 */

Это оставляет 2 "проблемы" для решения еще:

Обзорное описание; Я думаю, что @file позаботится о большинстве моих потребностей, но поскольку это для каждого файла, мне все равно понравится абзац или параграф типа "введение", который появляется перед описаниями включенных файлов.
Замена этого "домашнего" текста специальным текстом

Ответ 1

Создать домашнюю страницу

Создать файл уценки README.md

Создание jsdoc:

$ jsdoc path/to/js path/to/readme/README.md

Чтобы узнать больше об этой официальной документации

Изменить текст "Главная"

Я не думаю, что это правильный способ сделать это, но это работает.

Если у вас установлен jsdoc в вашем проекте, найдите файл шаблона в вашем рабочем каталоге, мой был:

./node_modules/jsdoc/templates/default/publish.js

Затем выполните поиск "Главная" с помощью команды поиска и замените ее текстом, следующим шагом будет указать шаблон при создании jsdoc:

 $ jsdoc ./src/scripts/ ./README.md -t node_modules/jsdoc/templates/default/

Ответ 2

Я не могу комментировать, поэтому я добавлю здесь примечание, чтобы прояснить, как делать все вещи в исходном вопросе, не изменяя шаблон по умолчанию, основанный на указаниях в файле, найденном в "\npm\ node_modules\jsdoc\templates", в котором объясняется, как создавать собственные шаблоны. Ниже описаны шаги по изменению заголовков "Home" в сгенерированной документации js для конкретных заголовков проекта (например, "MyDescription" ) и включают обзорный рекламный блок в верхней части главной страницы.

Действия

Во-первых, чтобы получить общий обзор на верхней части главной страницы документации js, вы должны сделать простой текстовый файл с именем README.md, написанный в Markdown, в соответствии с приведенным выше ответом и ссылкой. Весь текст появляется в верхней части страницы, если путь к этому файлу включен в командную строку, как показано выше, или ссылка добавляется в файл с именем conf.json, и в этом случае вы можете использовать jsdoc -c pathTo\conf.json для команды (см. пример в пункте 4 ниже). (Как поясняет ссылка, вы можете сделать файл с любым именем или расширением, если он находится в Markdown, и вы скажете jsdoc, где его найти).
Скопируйте папку и содержимое шаблона по умолчанию (\npm\node_modules\jsdoc\templates\default) в новый каталог, переименовав новую папку на что-то вроде myTemplate.
Используя приведенный выше совет для изменения текста "Главная", найдите файл с именем publish.js в новой папке myTemplate и замените "Домой" на "MyDescription" . Здесь нужно указать два момента: имя файла должно оставаться publish.js, а "Home" появилось в двух местах в моем исходном "publish.js", в строке
```
var nav = '<h2><a href="index.html">Home</a></h2>';
```
и в строке, начинающейся с generate('Home',....
Сообщите генератору jsdoc, где вы можете найти свой собственный шаблон (папка myTemplate) и файл обзора ( "README.md" ). Вы можете добавить -t pathTo\myTemplate в командную строку, или вы можете использовать очень короткую командную строку, jsdoc -c pathTo\conf.json, если вы создаете файл с именем conf.json в текстовом редакторе, что-то вроде файла ниже, в котором указывается источник, назначение и т.д. для документации. Этот файл помещает обзор на главную страницу, сообщая генератору doc использовать README.md в разделе "источник" и изменяет заголовки "Home" на новый заголовок "MyDescription" , используя новую папку myTemplate в разделе "opts".
```
{
    "tags": {
        "allowUnknownTags": true,
        "dictionaries": ["jsdoc","closure"]
    },
    "opts": {
        "template": "pathTo/myTemplate",
        "destination": "pathTo/myJScriptDocs",
        "recurse": true
    },
    "source": {
        "includePattern": ".+\\.js(doc)?$",
        "excludePattern": "(^|\\/|\\\\)_",
        "include": ["pathTo/myJSSources", "pathTo/README.md"]
    },
    "plugins": [],
    "templates": {
        "cleverLinks": false,
        "monospaceLinks": false
    }
}
```

Ответ 3

"Главная" кодируется (передается как title при создании индекса) в шаблоне по умолчанию, поэтому нет никакой переменной или конфигурации, которую вы могли бы установить для изменения этого заголовка.

Если несколько человек генерируют/редактируют документы, редактирование node_modules является очевидным не-go.

Достаточно создать layout.tmpl(или полный пользовательский шаблон, если вы его используете), указать JSDoc на него (вариант CLI или файл конфигурации) и заменить <?js= title ?> на <?js= title==='Home' ? 'Your Title' : title ?>.