Как быстро сгенерировать документацию JavaScript

внешний интерфейс JavaScript

JSDoc Template

Я помню, что великий бог сказал, постарайтесь не комментировать, кромеJsDoc. JsDoc может помочь нам быстро создать документацию по API с помощью стиля комментариев JsDoc. Напримерlodashдокументация.

JsDoc позволяет разработчикам разработать хороший стиль комментариев, а также позволяет комментировать и писать документы синхронно.

Предварительный просмотр шаблона myJsDoc

Стиль документации API в основном основан наjsDoc Template,myJsDocЭто стиль, производный от него. Все стили (включая стили кода) можно настраивать.

  • Общий стиль

预览

  • стиль уценки (github)

Установка JsDoc

 npm install -g jsdoc

Новое в корневом каталогеjsdoc.jsonИспользуется для настройки правил генерации, следующим образом (для конкретной конфигурацииmyJsDoc )

{
    "source": {
        // 需要生成文档的对应 js 路径
        "include": ["src/"],
        "includePattern": ".js$"
    },
    "opts": {
        "destination": "docs/", // 文档生成目录
        "readme": "docs/index.md", // 文档首页展示内容
        "template": "", // 文档模板
        "package": "package.json",
        "recurse": true,
        "tutorials": "docs/tutorials", // 生成教程内容
        "encoding": "utf8"
    },
    "templates": {
        // 模板配置，此处跟模板设置有关。
    },
    "plugins": ["plugins/markdown"],
    "markdown": {
        "tags": ["example"],
        "idInHeadings": true
    }
}

myjsdoc шаблон конфигурации элементов

{
    "templates": {
      "default": { // 可自定义指定添加到styles的目录
        "staticFiles": {
            "include": [
                 "./static"
            ]
        }
      },
      "css": [
        "styles/style.css" // 自定义样式
      ],
      "name": "Doc Template", // 文档名称
      "tabNames":{ // 导航名称
          "tutorials":"wiki",
          "apiName":"api"
      }
  }
}


git clone https://github.com/leer0911/myJsdoc.git
cd myJsDoc
npm i
npm run serve

здесь,serveЗадача в основном делает три вещи

  • Отслеживайте файлы scss, компилируйте их в css и храните в статическом каталоге.
  • Мониторинг файлов, связанных с JSDOC
  • Запустите gulp-jsdoc для создания документации

Все соответствующие ресурсы для шаблона находятся вstaticПод содержанием

  • каталог tmpllayout.tmplИзменить макет
  • publish.jsИзмените данные, переданные jsdoc, включая навигационную информацию, информацию о комментариях и т. д.
  • стиль модификации каталога scss

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

Ссылаться на

стиль кода

часто используемые теги jsdoc

tui jsdoc

Категории