diff --git a/gulpfile.ts b/gulpfile.ts index ee11a02dcb..0bc18dd7c4 100644 --- a/gulpfile.ts +++ b/gulpfile.ts @@ -13,6 +13,7 @@ import * as es from 'event-stream'; import cssnano = require('gulp-cssnano'); import * as uglifyComposer from 'gulp-uglify/composer'; import pug = require('gulp-pug'); +import stylus = require('gulp-stylus'); import * as rimraf from 'rimraf'; import chalk from 'chalk'; import imagemin = require('gulp-imagemin'); @@ -47,15 +48,32 @@ if (isDebug) { const constants = require('./src/const.json'); +require('./src/web/docs/api/endpoints/gulpfile.ts'); + gulp.task('build', [ 'build:js', 'build:ts', 'build:copy', - 'build:client' + 'build:client', + 'build:doc' ]); gulp.task('rebuild', ['clean', 'build']); +gulp.task('build:doc', [ + 'doc:endpoints', + 'doc:styles' +]); + +gulp.task('doc:styles', () => + gulp.src('./src/web/docs/**/*.styl') + .pipe(stylus()) + .pipe(isProduction + ? (cssnano as any)() + : gutil.noop()) + .pipe(gulp.dest('./built/web/assets/docs/')) +); + gulp.task('build:js', () => gulp.src(['./src/**/*.js', '!./src/web/**/*.js']) .pipe(gulp.dest('./built/')) diff --git a/package.json b/package.json index c20fd0c52a..69090349e1 100644 --- a/package.json +++ b/package.json @@ -53,6 +53,7 @@ "@types/is-root": "1.0.0", "@types/is-url": "1.2.28", "@types/js-yaml": "3.10.1", + "@types/mkdirp": "^0.5.2", "@types/mocha": "2.2.44", "@types/mongodb": "2.2.17", "@types/monk": "1.0.6", @@ -62,6 +63,7 @@ "@types/node": "8.5.1", "@types/page": "1.5.32", "@types/proxy-addr": "2.0.0", + "@types/pug": "^2.0.4", "@types/qrcode": "0.8.0", "@types/ratelimiter": "2.1.28", "@types/redis": "2.8.3", @@ -112,6 +114,7 @@ "gulp-pug": "3.3.0", "gulp-rename": "1.2.2", "gulp-replace": "0.6.1", + "gulp-stylus": "^2.6.0", "gulp-tslint": "8.1.2", "gulp-typescript": "3.2.3", "gulp-uglify": "3.0.0", @@ -122,6 +125,7 @@ "is-url": "1.2.2", "js-yaml": "3.10.0", "mecab-async": "0.1.2", + "mkdirp": "^0.5.1", "mocha": "4.0.1", "moji": "0.5.1", "mongodb": "2.2.33", diff --git a/src/web/app/app.styl b/src/web/app/app.styl index de66df74d4..22043b8833 100644 --- a/src/web/app/app.styl +++ b/src/web/app/app.styl @@ -1,29 +1,4 @@ -json('../../const.json') - -@charset 'utf-8' - -$theme-color = themeColor -$theme-color-foreground = themeColorForeground - -/* - ::selection - background $theme-color - color #fff -*/ - -* - position relative - box-sizing border-box - background-clip padding-box !important - tap-highlight-color rgba($theme-color, 0.7) - -webkit-tap-highlight-color rgba($theme-color, 0.7) - -html, body - margin 0 - padding 0 - scroll-behavior smooth - text-size-adjust 100% - font-family sans-serif +@import "../style" html &.progress @@ -96,17 +71,6 @@ body 100% transform rotate(360deg) -a - text-decoration none - color $theme-color - cursor pointer - - &:hover - text-decoration underline - - * - cursor pointer - code font-family Consolas, 'Courier New', Courier, Monaco, monospace diff --git a/src/web/docs/api/endpoints/gulpfile.ts b/src/web/docs/api/endpoints/gulpfile.ts new file mode 100644 index 0000000000..a2c3944709 --- /dev/null +++ b/src/web/docs/api/endpoints/gulpfile.ts @@ -0,0 +1,75 @@ +/** + * Gulp tasks + */ + +import * as fs from 'fs'; +import * as path from 'path'; +import * as glob from 'glob'; +import * as gulp from 'gulp'; +import * as pug from 'pug'; +import * as yaml from 'js-yaml'; +import * as mkdirp from 'mkdirp'; + +import config from './../../../../conf'; + +const parseParam = param => { + const id = param.type.match(/^id\((.+?)\)/); + const object = param.type.match(/^object\((.+?)\)/); + const isArray = /\[\]$/.test(param.type); + if (id) { + param.kind = 'id'; + param.type = 'string'; + param.entity = id[1]; + if (isArray) { + param.type += '[]'; + } + } + if (object) { + param.kind = 'object'; + param.type = 'object'; + param.def = object[1]; + if (isArray) { + param.type += '[]'; + } + } + + return param; +}; + +gulp.task('doc:endpoints', () => { + glob('./src/web/docs/api/endpoints/**/*.yaml', (globErr, files) => { + if (globErr) { + console.error(globErr); + return; + } + //console.log(files); + files.forEach(file => { + const ep = yaml.safeLoad(fs.readFileSync(file, 'utf-8')); + const vars = { + endpoint: ep.endpoint, + url: `${config.api_url}/${ep.endpoint}`, + desc: ep.desc, + params: ep.params.map(p => parseParam(p)), + paramDefs: Object.keys(ep.paramDefs).map(key => ({ + name: key, + params: ep.paramDefs[key].map(p => parseParam(p)) + })), + res: ep.res.map(p => parseParam(p)) + }; + pug.renderFile('./src/web/docs/api/endpoints/view.pug', vars, (renderErr, html) => { + if (renderErr) { + console.error(renderErr); + return; + } + const htmlPath = `./built/web/docs/api/endpoints/${ep.endpoint}.html`; + mkdirp(path.dirname(htmlPath), (mkdirErr) => { + if (mkdirErr) { + console.error(mkdirErr); + return; + } + fs.writeFileSync(htmlPath, html, 'utf-8'); + }); + }); + }); + }); +}); diff --git a/docs/api/endpoints/posts/create.yaml b/src/web/docs/api/endpoints/posts/create.yaml similarity index 87% rename from docs/api/endpoints/posts/create.yaml rename to src/web/docs/api/endpoints/posts/create.yaml index db91775cb6..b6613038a7 100644 --- a/docs/api/endpoints/posts/create.yaml +++ b/src/web/docs/api/endpoints/posts/create.yaml @@ -7,31 +7,31 @@ desc: params: - name: "text" type: "string" - required: true + optional: false desc: ja: "投稿の本文" en: "Text of a post" - name: "media_ids" type: "id(DriveFile)[]" - required: false + optional: true desc: ja: "添付するメディア" en: "Media you want to attach" - name: "reply_id" type: "id(Post)" - required: false + optional: true desc: ja: "返信する投稿" en: "A post you want to reply" - name: "repost_id" type: "id(Post)" - required: false + optional: true desc: ja: "引用する投稿" en: "A post you want to quote" - name: "poll" type: "object(poll)" - required: false + optional: true desc: ja: "投票" en: "A poll" @@ -40,7 +40,7 @@ paramDefs: poll: - name: "choices" type: "string[]" - required: true + optional: false desc: ja: "投票の選択肢" en: "Choices of a poll" @@ -48,6 +48,7 @@ paramDefs: res: - name: "created_post" type: "entity(Post)" + optional: false desc: ja: "作成した投稿" en: "A post that created" diff --git a/src/web/docs/api/endpoints/style.styl b/src/web/docs/api/endpoints/style.styl new file mode 100644 index 0000000000..12c06fe3af --- /dev/null +++ b/src/web/docs/api/endpoints/style.styl @@ -0,0 +1,16 @@ +@import "../../style" + +#url + padding 8px 12px + font-family Consolas, 'Courier New', Courier, Monaco, monospace + color #fff + background #222e40 + border-radius 4px + +table + .name + font-weight bold + + .type + font-family Consolas, 'Courier New', Courier, Monaco, monospace + diff --git a/src/web/docs/api/endpoints/view.pug b/src/web/docs/api/endpoints/view.pug new file mode 100644 index 0000000000..d9de9cb74a --- /dev/null +++ b/src/web/docs/api/endpoints/view.pug @@ -0,0 +1,60 @@ +doctype html + +mixin i18n(xs) + each text, lang in xs + span(class=`i18n ${lang}`)= text + +mixin table(params) + table + thead: tr + th Name + th Type + th Optional + th Description + tbody + each param in params + tr + td.name= param.name + td.type + if param.kind == 'id' + | #{param.type} (ID of + = ' ' + a(href=`/docs/api/entities/${param.entity}`)= param.entity + | ) + else if param.kind == 'object' + | #{param.type} ( + a(href=`#${param.def}`)= param.def + | ) + else + = param.type + td.optional= param.optional.toString() + td.desc: +i18n(param.desc) + +html + head + meta(charset="UTF-8") + title #{endpoint} | Misskey API + link(rel="stylesheet" href="/assets/docs/api/endpoints/style.css") + + body + main + h1= endpoint + + p#url= url + + p#desc: +i18n(desc) + + section + h2 Params + +table(params) + + if paramDefs + each paramDef in paramDefs + section(id= paramDef.name) + h3= paramDef.name + +table(paramDef.params) + + section + h2 Response + +table(res) + diff --git a/src/docs/api/entities/post.pug b/src/web/docs/api/entities/post.pug similarity index 100% rename from src/docs/api/entities/post.pug rename to src/web/docs/api/entities/post.pug diff --git a/src/docs/api/entities/user.pug b/src/web/docs/api/entities/user.pug similarity index 100% rename from src/docs/api/entities/user.pug rename to src/web/docs/api/entities/user.pug diff --git a/src/docs/api/getting-started.md b/src/web/docs/api/getting-started.md similarity index 100% rename from src/docs/api/getting-started.md rename to src/web/docs/api/getting-started.md diff --git a/src/docs/api/library.md b/src/web/docs/api/library.md similarity index 100% rename from src/docs/api/library.md rename to src/web/docs/api/library.md diff --git a/src/docs/index.md b/src/web/docs/index.md similarity index 100% rename from src/docs/index.md rename to src/web/docs/index.md diff --git a/src/docs/link-to-twitter.md b/src/web/docs/link-to-twitter.md similarity index 100% rename from src/docs/link-to-twitter.md rename to src/web/docs/link-to-twitter.md diff --git a/src/web/docs/style.styl b/src/web/docs/style.styl new file mode 100644 index 0000000000..9014df87fe --- /dev/null +++ b/src/web/docs/style.styl @@ -0,0 +1,69 @@ +@import "../style" + +body + margin 0 + color #34495e + +main + padding 32px + width 100% + max-width 700px + +footer + padding:32px 0 0 0 + margin 32px 0 0 0 + border-top solid 1px #eee + + .copyright + margin 16px 0 0 0 + color #aaa + +section + margin 32px 0 + +h1 + margin 0 0 24px 0 + padding 16px 0 + font-size 1.5em + border-bottom solid 2px #eee + +h2 + margin 0 0 24px 0 + padding 0 0 16px 0 + font-size 1.4em + border-bottom solid 1px #eee + +h3 + margin 0 + padding 0 + font-size 1.25em + +h4 + margin 0 + +p + margin 1em 0 + line-height 1.6em + +table + width 100% + border-spacing 0 + border-collapse collapse + + thead + font-weight bold + border-bottom solid 2px #eee + + tr + th + text-align left + + tbody + tr + border-bottom dashed 1px #eee + + th, td + padding 8px 16px + +.i18n:not(.ja) + display none diff --git a/src/docs/tou.md b/src/web/docs/tou.md similarity index 100% rename from src/docs/tou.md rename to src/web/docs/tou.md diff --git a/src/web/server.ts b/src/web/server.ts index 1d3687f89e..38e87754f3 100644 --- a/src/web/server.ts +++ b/src/web/server.ts @@ -63,6 +63,12 @@ app.get('/manifest.json', (req, res) => */ app.get(/\/api:url/, require('./service/url-preview')); +/** + * Docs + */ +app.get(/^\/docs\/([a-z_\-\/]+?)$/, (req, res) => + res.sendFile(`${__dirname}/docs/${req.params[0]}.html`)); + /** * Routing */ diff --git a/src/web/style.styl b/src/web/style.styl new file mode 100644 index 0000000000..573df10d78 --- /dev/null +++ b/src/web/style.styl @@ -0,0 +1,38 @@ +json('../const.json') + +@charset 'utf-8' + +$theme-color = themeColor +$theme-color-foreground = themeColorForeground + +/* + ::selection + background $theme-color + color #fff +*/ + +* + position relative + box-sizing border-box + background-clip padding-box !important + tap-highlight-color rgba($theme-color, 0.7) + -webkit-tap-highlight-color rgba($theme-color, 0.7) + +html, body + margin 0 + padding 0 + scroll-behavior smooth + text-size-adjust 100% + font-family sans-serif + +a + text-decoration none + color $theme-color + cursor pointer + + &:hover + text-decoration underline + + * + cursor pointer +