From 724f1c1434f98ec0881a1182d10979170b4bc166 Mon Sep 17 00:00:00 2001 From: kazuya kawaguchi Date: Tue, 24 Nov 2020 14:16:19 +0900 Subject: [PATCH] docs: updates --- .gitignore | 2 +- README.md | 16 +-- docs/.vitepress/config.js | 54 +++------ docs/api/index.md | 1 - docsgen.config.js | 7 ++ package.json | 3 +- scripts/api/processor.js | 223 ++++++++++++++------------------------ scripts/api/resolver.js | 40 ++++++- scripts/docsgen.config.js | 7 -- 9 files changed, 151 insertions(+), 202 deletions(-) delete mode 100644 docs/api/index.md create mode 100644 docsgen.config.js delete mode 100644 scripts/docsgen.config.js diff --git a/.gitignore b/.gitignore index f4ef48733..c992f6527 100644 --- a/.gitignore +++ b/.gitignore @@ -1,5 +1,5 @@ dist -docs/api/vue-i18** +docs/api/ types temp coverage diff --git a/README.md b/README.md index d91face2e..f7188a9c0 100644 --- a/README.md +++ b/README.md @@ -54,14 +54,14 @@ If you use stable Vue I18n version, see this [repository](https://github.com/kaz New style API for Vue Composition API. See the following docs: -- [createI18n](https://vue-i18n-next.intlify.dev/api/vue-i18n-function.html#createi18n) - - [I18nOptions](https://vue-i18n-next.intlify.dev/api/vue-i18n-typealias.html#i18noptions) - - [ComposerOptions](https://vue-i18n-next.intlify.dev/api/vue-i18n-interface.html#composeroptions) - - [VueI18nOptions](https://vue-i18n-next.intlify.dev/api/vue-i18n-interface.html#vuei18noptions) -- [useI18n](https://vue-i18n-next.intlify.dev/api/vue-i18n-function.html#usei18n) - - [ComposerOptions](https://vue-i18n-next.intlify.dev/api/vue-i18n-interface.html#composeroptions) -- [Composer](https://vue-i18n-next.intlify.dev/api/vue-i18n-interface.html#composer) -- [VueI18n](https://vue-i18n-next.intlify.dev/api/vue-i18n-interface.html#vuei18n) +- [createI18n](https://vue-i18n-next.intlify.dev/api/general.html#createi18n) + - [I18nOptions](https://vue-i18n-next.intlify.dev/api/general.html#i18noptions) + - [ComposerOptions](https://vue-i18n-next.intlify.dev/api/composition.html#composeroptions) + - [VueI18nOptions](https://vue-i18n-next.intlify.dev/api/legacy.html#vuei18noptions) +- [useI18n](https://vue-i18n-next.intlify.dev/api/compositiono.html#usei18n) + - [ComposerOptions](https://vue-i18n-next.intlify.dev/api/compositino.html#composeroptions) +- [Composer](https://vue-i18n-next.intlify.dev/api/composition.html#composer) +- [VueI18n](https://vue-i18n-next.intlify.dev/api/legacy.html#vuei18n) ### `` Component (formerly called `` component) diff --git a/docs/.vitepress/config.js b/docs/.vitepress/config.js index 0bfda2df7..2719b7af1 100644 --- a/docs/.vitepress/config.js +++ b/docs/.vitepress/config.js @@ -1,6 +1,3 @@ -const { readdirSync } = require('fs') -const { resolve, basename } = require('path') - /** @typedef {import('vitepress').UserConfig} UserConfig */ /** @type {UserConfig['head']} */ @@ -36,8 +33,7 @@ const config = { }, { text: 'API Reference', - link: '/api/' - //link: '/api/vue-i18n-general' + link: '/api/general' }, { text: 'Chnagelog', @@ -145,44 +141,24 @@ const config = { link: '/v8-docs', }, ], - '/api/': getSidebarApi('vue-i18n'), - // '/api/': [ - // { - // text: 'General', - // link: '/api/vue-i18n-general' - // }, - // { - // text: 'Legacy API', - // link: '/api/vue-i18n-legacy' - // }, - // { - // text: 'Composition API', - // link: '/api/vue-i18n-composition' - // } - // ] + '/api/': [ + { + text: 'General', + link: '/api/general' + }, + { + text: 'Legacy API', + link: '/api/legacy' + }, + { + text: 'Composition API', + link: '/api/composition' + } + ] } } } } } -function getSidebarApi(target) { - const API_TITLE_MAPS = { - function: 'Functions', - interface: 'Interfaces', - typealias: 'Type Aliases', - variable: 'Variables', - class: 'Classes' - } - return readdirSync(resolve(__dirname, '../api')) - .map(file => basename(file, '.md')) - .filter(file => file.includes(target)) - .map(file => { - return { - text: API_TITLE_MAPS[file.split('-').pop()], - link: `/api/${file}` - } - }) -} - module.exports = config diff --git a/docs/api/index.md b/docs/api/index.md deleted file mode 100644 index dd5b8dcea..000000000 --- a/docs/api/index.md +++ /dev/null @@ -1 +0,0 @@ -## API Reference diff --git a/docsgen.config.js b/docsgen.config.js new file mode 100644 index 000000000..857851749 --- /dev/null +++ b/docsgen.config.js @@ -0,0 +1,7 @@ +const linkReferencer = require('./scripts/api/resolver') +const processor = require('./scripts/api/processor') + +module.exports = { + linkReferencer, + processor +} diff --git a/package.json b/package.json index ddeda8387..7e24d4780 100644 --- a/package.json +++ b/package.json @@ -152,8 +152,7 @@ "clean:type": "rm -rf ./types/** ./temp ./dist/vue-i18n.d.ts", "coverage": "opener coverage/lcov-report/index.html", "dev:e2e": "jest --runInBand --config ./jest.e2e.config.js", - "docs:apigen": "api-docs-gen ./temp/vue-i18n.api.json -o ./docs/api", - "docs:apigen1": "api-docs-gen ./temp/vue-i18n.api.json -o ./docs/api -c ./scripts/docsgen.config.js --tsdoc-config ./tsdoc.json", + "docs:apigen": "api-docs-gen ./temp/vue-i18n.api.json -o ./docs/api -c ./docsgen.config.js -g noprefix -t ./tsdoc.json", "docs:build": "yarn docs:setup && vitepress build docs", "docs:dev": "vitepress dev docs", "docs:serve": "vitepress serve docs", diff --git a/scripts/api/processor.js b/scripts/api/processor.js index 9bd6970fc..9f0fc4539 100644 --- a/scripts/api/processor.js +++ b/scripts/api/processor.js @@ -62,13 +62,54 @@ function process(model, pkg, style, resolver, customTags) { console.log('misc models', miscModels) const contents = [] - contents.push(buildGeneral(generalModels)) - contents.push(buildLegacy(legacyModels)) - contents.push(buildComposition(compositionModels)) + contents.push(buildContents(generalModels, 'General', 'general.md')) + contents.push(buildContents(legacyModels, 'Legacy API', 'legacy.md')) + contents.push( + buildContents(compositionModels, 'Compositoin API', 'composition.md') + ) // contents.push(buildMisc(miscModels)) return contents } + function buildContents(models, title, filename) { + const builder = createContentBuilder() + builder.pushline(`# ${title}`) + builder.newline() + + models.sort((a, b) => a.name.localeCompare(b.name)) + models.forEach(m => { + builder.pushline(`## ${m.name}`) + builder.newline() + switch (m.type) { + case 'Function': + buildFunction(m, builder) + break + case 'Enum': + buildEnum(m, builder) + break + case 'Interface': + buildInterface(m, builder) + break + case 'Class': + buildClass(m, builder) + break + case 'TypeAlias': + buildTypeAlias(m, builder) + break + case 'Variable': + buildVariable(m, builder) + break + default: + break + } + }) + + return { + filename: filename, + body: builder.content + } + } + function buildFunction(model, builder) { if (model.summary) { builder.pushline(model.summary) @@ -84,7 +125,7 @@ function process(model, pkg, style, resolver, customTags) { } if (model.remarks) { - builder.pushline(`### Remarks`) + builder.pushline(`**Remarks**`) builder.newline() builder.pushline(model.remarks) builder.newline() @@ -102,7 +143,7 @@ function process(model, pkg, style, resolver, customTags) { } if (model.returns) { - builder.pushline(`### Returns`) + builder.pushline(`**Remarks**`) builder.newline() builder.pushline(model.returns) builder.newline() @@ -123,7 +164,7 @@ function process(model, pkg, style, resolver, customTags) { if (model.examples) { if (model.examples.length > 0) { - builder.pushline(`### Examples`) + builder.pushline(`**Examples**`) builder.newline() let count = 1 for (const e of model.examples) { @@ -157,7 +198,7 @@ function process(model, pkg, style, resolver, customTags) { } if (model.remarks) { - builder.pushline(`### Remarks`) + builder.pushline(`**Remarks**`) builder.newline() builder.pushline(model.remarks) builder.newline() @@ -165,7 +206,7 @@ function process(model, pkg, style, resolver, customTags) { if (model.examples) { if (model.examples.length > 0) { - builder.pushline(`### Examples`) + builder.pushline(`**Examples**`) builder.newline() let count = 1 for (const e of model.examples) { @@ -213,7 +254,7 @@ function process(model, pkg, style, resolver, customTags) { } if (model.remarks) { - builder.pushline(`#### Remarks`) + builder.pushline(`**Remarks**`) builder.newline() builder.pushline(model.remarks) builder.newline() @@ -221,7 +262,7 @@ function process(model, pkg, style, resolver, customTags) { if (model.examples) { if (model.examples.length > 0) { - builder.pushline(`#### Examples`) + builder.pushline(`**Examples**`) builder.newline() let count = 1 for (const e of model.examples) { @@ -253,7 +294,7 @@ function process(model, pkg, style, resolver, customTags) { } if (model.remarks) { - builder.pushline(`#### Remarks`) + builder.pushline(`**Remarks**`) builder.newline() builder.pushline(model.remarks) builder.newline() @@ -292,7 +333,7 @@ function process(model, pkg, style, resolver, customTags) { if (model.examples) { if (model.examples.length > 0) { - builder.pushline(`#### Examples`) + builder.pushline(`**Examples**`) builder.newline() let count = 1 for (const e of model.examples) { @@ -326,7 +367,7 @@ function process(model, pkg, style, resolver, customTags) { } if (model.remarks) { - builder.pushline(`### Remarks`) + builder.pushline(`**Remarks**`) builder.newline() builder.pushline(model.remarks) builder.newline() @@ -334,7 +375,7 @@ function process(model, pkg, style, resolver, customTags) { if (model.examples) { if (model.examples.length > 0) { - builder.pushline(`### Examples`) + builder.pushline(`**Examples**`) builder.newline() let count = 1 for (const e of model.examples) { @@ -351,143 +392,45 @@ function process(model, pkg, style, resolver, customTags) { } } - function buildVariable(model, builder) {} - - function buildGeneral(models) { - const builder = createContentBuilder() - builder.pushline(`# General`) - builder.newline() - - models.sort((a, b) => a.name.localeCompare(b.name)) - models.forEach(m => { - builder.pushline(`## ${m.name}`) + function buildVariable(model, builder) { + if (model.summary) { + builder.pushline(model.summary) builder.newline() - switch (m.type) { - case 'Function': - buildFunction(m, builder) - break - case 'Enum': - buildEnum(m, builder) - break - case 'Interface': - buildInterface(m, builder) - break - case 'Class': - buildClass(m, builder) - break - case 'TypeAlias': - buildTypeAlias(m, builder) - break - case 'Variable': - buildVariable(m, builder) - break - default: - break - } - }) - - return { - filename: 'general.md', - body: builder.content } - } - function buildLegacy(models) { - const builder = createContentBuilder() - builder.pushline(`# Legacy API`) - builder.newline() - - models.sort((a, b) => a.name.localeCompare(b.name)) - models.forEach(m => { - builder.pushline(`## ${m.name}`) + if (model.signature) { + builder.pushline(`**Signature:**`) + builder.pushline('```typescript') + builder.pushline(model.signature) + builder.pushline('```') builder.newline() - switch (m.type) { - case 'Function': - buildFunction(m, builder) - break - case 'Enum': - buildEnum(m, builder) - break - case 'Interface': - buildInterface(m, builder) - break - case 'Class': - buildClass(m, builder) - break - case 'TypeAlias': - buildTypeAlias(m, builder) - break - case 'Variable': - buildVariable(m, builder) - break - default: - break - } - }) - - return { - filename: 'legacy.md', - body: builder.content } - } - - function buildComposition(models) { - const builder = createContentBuilder() - builder.pushline(`# Composition API`) - builder.newline() - models.sort((a, b) => a.name.localeCompare(b.name)) - models.forEach(m => { - builder.pushline(`## ${m.name}`) + if (model.remarks) { + builder.pushline(`**Remarks**`) builder.newline() - switch (m.type) { - case 'Function': - buildFunction(m, builder) - break - case 'Enum': - buildEnum(m, builder) - break - case 'Interface': - buildInterface(m, builder) - break - case 'Class': - buildClass(m, builder) - break - case 'TypeAlias': - buildTypeAlias(m, builder) - break - case 'Variable': - buildVariable(m, builder) - break - default: - break - } - }) - - return { - filename: 'composition.md', - body: builder.content - } - } - - /* - function buildMisc(models) { - const builder = createContentBuilder() - builder.pushline(`# Misc`) - builder.newline() - - models.sort((a, b) => a.name.localeCompare(b.name)) - models.forEach(m => { - builder.pushline(`## ${m.name}`) + builder.pushline(model.remarks) builder.newline() - }) + } - return { - filename: 'misc.md', - body: builder.content + if (model.examples) { + if (model.examples.length > 0) { + builder.pushline(`**Examples**`) + builder.newline() + let count = 1 + for (const e of model.examples) { + if (model.examples.length > 1) { + builder.pushline(`**Example ${count}:**`) + builder.newline() + } + builder.pushline(e) + builder.newline() + count++ + } + builder.newline() + } } } - */ const models = parse() const contents = build(models) diff --git a/scripts/api/resolver.js b/scripts/api/resolver.js index 2f09a7ed5..b4f8462e0 100644 --- a/scripts/api/resolver.js +++ b/scripts/api/resolver.js @@ -1,9 +1,27 @@ const { getSafePathFromDisplayName } = require('api-docs-gen') +function getContentName(item, customTags) { + const docs = item.tsdocComment + if (!docs) { + return '' + } + const modifierTags = docs.modifierTagSet.nodes + ? docs.modifierTagSet.nodes.map(n => n.tagName) + : [] + if (modifierTags.length === 0) { + return '' + } + if (!customTags.some(tag => modifierTags.includes(tag))) { + return '' + } + return modifierTags[0].split('@VueI18n')[1].toLowerCase() +} + function resolve(style, item, model, pkg, customTags) { - let baseName = '' + const contentName = getContentName(item, customTags) + let qualifiedName = '' for (const hierarchyItem of item.getHierarchy()) { - const qualifiedName = getSafePathFromDisplayName(hierarchyItem.displayName) + const displayName = getSafePathFromDisplayName(hierarchyItem.displayName) switch (hierarchyItem.kind) { case 'Enum': case 'Function': @@ -11,13 +29,27 @@ function resolve(style, item, model, pkg, customTags) { case 'TypeAlias': case 'Class': case 'Interface': - baseName = `#${qualifiedName}` + qualifiedName = displayName break default: break } } - return baseName + + if (contentName) { + if (!qualifiedName) { + return contentName + } else { + return `${contentName}#${qualifiedName}` + } + } else { + if (qualifiedName) { + return `#${qualifiedName}` + } else { + console.warn('cannnot resolve ...') + return '' + } + } } module.exports = resolve diff --git a/scripts/docsgen.config.js b/scripts/docsgen.config.js deleted file mode 100644 index 915a93d7c..000000000 --- a/scripts/docsgen.config.js +++ /dev/null @@ -1,7 +0,0 @@ -const linkReferencer = require('./api/resolver') -const processor = require('./api/processor') - -module.exports = { - linkReferencer, - processor -}