中文文档

[popomore]

• 介绍 intro
  • 什么是 egg（是什么，解决什么问题，egg 重要特性，cluster，插件机制） docs: Add intro/index.md #246 @popomore
  • 基于 koa（介绍 koa，并介绍做了什么扩展） docs: egg and koa #179 @dead-horse
  • hello world 快速上手（给一个 example 链接，解读代码，过一下 egg 基本功能） docs: quickstart #217 @atian25
• 功能详解 basics（只有 app，感知不到 agent）
  • env（默认环境，自定义环境） doc: add basics/env.md #178 @popomore
  • config（根据环境加载，顺序，appInfo，如何获取）docs: add basics/config.md #188 @popomore
  • middleware（koa 中间件，参数，中间件顺序）docs: basics/middleware #194 @dead-horse
  • router @leoner （路由规则，原则，API）docs: add basics/router.md #203
  • controller（controller, session ...）docs: add controller #209 @dead-horse
  • service docs: add service doc #221 @leoner
  • schedule @dead-horse docs: add schedule #202
  • extend（extend koa api，加载顺序） doc: guide/basics/extend doc #187 @shaoshuai0102
  • 启动自定义（app.js）doc: app start #193 @shaoshuai0102
• 核心功能（内置插件功能） core
  • security（安全介绍） docs: add security plugin doc #196 @jtyjty99999
  • passport/userservice
  • userrole @gxcsoccer
  • tracer @fengmk2
  • httpclient docs: core/httpclient.md #197 @fengmk2
  • 日志（logrotator，logger，自定义，transport）docs: add core/logger.md #204 @shaoshuai0102
  • 异常处理 @dead-horse
  • i18n docs: add core/i18n.md #208 @shaoshuai0102
  • 本地开发和 debug docs: add core/development.md #214 @shaoshuai0102
  • 应用单元测试（用例写法，常用工具介绍，egg-mock） docs: add core/unittest.md #199 @fengmk2
• 最佳实践 practice
  • view and assets（介绍 egg-view-nunjucks，如何使用 view，自定义 view，静态文件的例子） docs: view #228 @atian25
  • 访问 MySQL docs: add mysql doc #234 @jtyjty99999
  • 实现 RESTful API docs: add RESTful documents #247 @dead-horse
  • 渐进式开发, 介绍 app -> plugin -> framework 的演变 docs: add progressive usage #268 @atian25
• 高级功能 advanced
  • 部署（构建打包，install-node，环境依赖，部署，可以添加一个 docker 的例子）
  • cluster 模式，客户端规范（cluster-client，这里引入 agent 概念）feat: add cluster-client #191 @gxcsoccer
  • 开发插件（包括插件原理）doc: add plugin doc #224 @gxcsoccer
  • 开发框架（框架继承，如何扩展，原理） docs: add advanced/framework.md #225 @popomore
  • 加载器（加载顺序，自定义加载） docs: add advanced/loader.md #198 @popomore

[fengmk2]

直接 README 吧，多语言使用 README.zh-CN.md 类似这样的。

[atian25]

先在 README + docs 下.

后面再配置个 travis gitbook 推到 pages.

[atian25]

https://github.com/esdoc/esdoc

[atian25]

progit 的文档翻译不知道是如何同步的, 下面有个百分比.
而且翻译者如何知道下次更新是基于哪个点开始? 难道每次都记录上次的起始基点?

• https://github.com/progit/progit2/blob/master/CONTRIBUTING.md
• https://progit.org/translations

[fengmk2]

尽量中英文文档修改同时提交。

[atian25]

Api docs 这个 @popomore 你来搞下?

[popomore]

eggjs/egg-core#10 (comment) 这里有个 jsdoc 需要优化

[popomore]

文档怎么搞还没结论，是不是就做个页面其他放在 egg docs 目录？

[atian25]

• guide 文档通过 markdown 构建
• api 用 jsdoc 或 esdoc 构建

需讨论的是，

• docs下加一个 site 目录放官网的页面文件
• ghpage
• 单独的仓库用于自动构建发布

[atian25]

docs 下的 guide 如何多语言呢？

[popomore]

就是按目录分语言

docs
|- zh-CN
`- en

[popomore]

自动构建的话直接 push 到 https://github.com/eggjs/eggjs.org

[crazybear]

请问各位大大，什么时候发布文档呢，眼巴巴的看了好几天了

[popomore]

大概 10月，还在写

[zhoudaqing]

@fengmk2 @atian25 @popomore 文档能不能完善一下？ 刚刚使用egg很痛苦，靠猜和看源代码太痛苦了，希望能尽快完善一下。

[popomore]

@zhoudaqing 好的，我们尽快

[popomore]

先写中文 https://eggjs.org/zh-cn/guide/

[popomore]

cc @HiuYanChong

[popomore]

目录结构已更新

[18601673727]

催更..

[fengmk2]

插件 README 文档规范

• 必须包含以下章节
  • 依赖说明（无则省略）
  • 开启插件
  • 使用场景
  • 详细配置（无则省略）
  • 单元测试（无则省略，例如 schedule 如何触发）
  • 提问交流: 请到 egg issues 异步交流。

示例:

• egg-mysql https://github.com/eggjs/egg-mysql/pull/3/files#diff-0d10b069ec2726b1e9d0c0b0eae34f3eR118

[jiangzhuo]

催更..

[atian25]

@18601673727 @jiangzhuo 你们可以先看下 https://github.com/eggjs/egg/blob/master/SPECIFICATION.zh_CN.md

[shaoshuai0102]

认领 本地开发和 debug

[popomore]

领框架开发

[fengmk2]

接手单元测试

[gxcsoccer]

领 passport/userservice（userrole）

[mansonchor]

「访问 MYSQL 要不我认领下？今天内提交PR

@jtyjty99999 确认一下你开始写了没？」

@jtyjty99999 快写完了，我帮忙补充和review吧

[popomore]

文档现在可访问 https://eggjs.org/zh-cn/intro/egg-and-koa.html 但还需要优化

• 支持默认 lang，现在默认是中文，就是 /xx == /zh-cn/xx。如果某个语言文档默认缺失使用默认文档补全。
• 侧栏选中当前项
• url 去掉 .html 后缀
• 支持 toc
• 支持多语言选择
• 静态文件支持 hash

[atian25]

域名要不要做个 cn.eggjs.org 的映射?

[fengmk2]

@atian25 没必要子域名，太丑

[popomore]

What's egg

• http://sailsjs.com/whats-that
• http://guides.rubyonrails.org/getting_started.html

[popomore]

practice 可以改成 tutorials，这个感觉比较常用

[atian25]

eslint

[atian25]

少了个 static

[popomore]

部署先等这个做完，先隐藏 #241

[popomore]

支持默认 lang，现在默认是中文，就是 /xx == /zh-cn/xx。如果某个语言文档默认缺失使用默认文档补全。

先把这个做好就可以推广了

[atian25]

README 也需要修改下里面的链接

[popomore]

static 是啥？

[atian25]

文档里面有 egg-static 了么？

[atian25]

• 框架章节有个链接失效 example/framework feat: add missing framework example examples#8
• boilerplate 列表介绍?
• loader 增加如何定制 this.model.xx 的示例?

[atian25]

#257

[atian25]

• ~ 和 ^ 的选择 @dead-horse

[atian25]

• [ ]『什么是 egg』 需要优化，更老少皆宜一点。

另外，可以加入一些『渐进式』的描述 #268 (comment)

@popomore

[popomore]

之后需要增加的 #276

[popomore]

这个 issue 没问题的话先关了，后面文档补充单独提 issue

[popomore]

@atian25 boilerplate 需要介绍？

[atian25]

不用了, 现在文档里面感觉也没地方塞.

或者在 egg-init 那里列举下官方的骨架就好了.

[atian25]

@eggjs/core any plan on this?

[atian25]

missing passport document