Egg: 中文文档

[popomore]

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

https://github.com/eggjs/egg-core/pull/10#issue-171550881 这里有个 jsdoc 需要优化

[popomore]

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

[atian25]

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

需讨论的是，

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

[atian25]

docs 下的 guide 如何多语言呢？

[popomore]

就是按目录分语言

|- 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

[fengmk2]

领 tracer

[fengmk2]

领 httpclient

[gxcsoccer]

领 cluster & 插件

[shaoshuai0102]

领 logger

[popomore]

开始写 loader

[popomore]

直播贴 https://cnodejs.org/topic/5870e9da04dcf9a706a745f0

[fengmk2]

示例代码都放到 https://github.com/eggjs/examples

[dead-horse]

https://github.com/sparanoid/chinese-copywriting-guidelines

[fengmk2]

领 passport

[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 但还需要优化

• [x] 支持默认 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]

部署先等这个做完，先隐藏 https://github.com/eggjs/egg/issues/241

[popomore]

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

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

[atian25]

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

[popomore]

static 是啥？

[atian25]

文档里面有 egg-static 了么？

[atian25]

• [x] 框架章节有个链接失效 example/framework https://github.com/eggjs/examples/pull/8
• [ ] boilerplate 列表介绍?
• [ ] loader 增加如何定制 this.model.xx 的示例?

[atian25]

https://github.com/eggjs/egg/pull/257

[atian25]

• [ ] ~ 和 ^ 的选择 @dead-horse

[atian25]

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

另外，可以加入一些『渐进式』的描述 https://github.com/eggjs/egg/pull/268#issuecomment-273366035

@popomore

[popomore]

之后需要增加的 https://github.com/eggjs/egg/issues/276

[popomore]

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

[popomore]

@atian25 boilerplate 需要介绍？

[atian25]

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

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

[atian25]

@eggjs/core any plan on this?

[atian25]

missing passport document