-
-
Notifications
You must be signed in to change notification settings - Fork 1.8k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
feat: guide toc #55
feat: guide toc #55
Conversation
- app/extend/agent.js | ||
- app.js | ||
- agent.js | ||
* Customization Guide |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
这里想表达的是一种最佳实践, 渐进式的代码抽离思路.
要区分英文和中文?在两个目录下都放个 summary |
* Service | ||
* Config | ||
* Middleware | ||
* Context |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
这堆合并到 extend 吧?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
这里不是扩展的意思, 而是介绍他们的 API
重新更新了目录, 以及对应的文件说明, 大家再看看. |
@@ -0,0 +1 @@ | |||
安全很重要, 文档目录上需要有这个, 但是否需要有这个实体文件要看看具体写的时候, 是外链去 egg-security 还是怎么样 |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
尽量外链过去吧,比较跟随代码的文档会更加及时。
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
好, 那文件不用存在, 但 summary 那里目录树最好独立一个项, 显眼一点, 而不是混在 plugin 的内置插件表格里面
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
cookie 和 session 这类的要加在目录树上么
文档不按语言来分子目录吧,按之前的约定好了
|
- Cluster Management | ||
- Loader | ||
- Security | ||
|
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
空行去掉
每个路径都带语言,外链写起来麻烦 |
e47fb2c
to
fa96c59
Compare
Here is two cents. I do agree that we need to separate the docs into its own structure instead of one giant page including everything that you could possible think of. To be able to get there, we need to have a solid Chinese version first. The current commit has all files stored in I do like the bullet points for each file, it is simple and clear. How does it relate to the current Once you are in the good stage, you should merge this PR into the master. Then we can start two different PRs to target two different languages. I suggest to have a perfect story and solid explanation for Chinese version. Then I can have a better understanding of story, and come up with better docs for EN. Those are just my 2 cents. Let me know what you think. |
|
When I reviewed It is good to separate them into individual standard. It is a trend. I saw that we have Gitbook script written in the project and ready to spit out the documentation in the pretty book format based on JSConf is sept 3-4. Are we still targeting to open source the project on stage? If so, we should get the effort started and have the doc ready by then. In short, let us get rid of |
@atian25 Do write it based on the |
For this PR, @atian25 should get it reviewed with @fengmk2 , @popomore , and @dead-horse. Locked down all the bullet points and file structure. So that we have a solid foundation to build upon. Then we expand to have more contents for each bullet point. |
- Service | ||
- Config | ||
- Middleware | ||
- Context |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
context, application, request, response 放到最前面?突出这些是和 koa 一致的
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
这里可以加上 schedule
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
schedule , security, cookie , session 这些都是内置的插件, 我在考虑:
- 目录树上可以加上它们, 但是点击进去都是同一个页面
- 这个页面里面就一个简单的表格: 插件, 一句话介绍, 仓库链接
Agree! @atian25 web.md 更多的是写明一些约定会比较好,不应该大改它了。 |
- Application | ||
- Request | ||
- Response | ||
- Locals |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Locals 和 Form 直观上不属于 basic usage? Helper 是不是放到 View 的里面?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Helper 目前的定位, 有点怪怪, 貌似不是只给 View 用的吧, 有点 Utils 的感觉. View 那里又有个 ViewHelper 来继承 Helper
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
locals 和 form 放到 advanced 好像也有点尴尬, 上不上下不下的. 都OK,反正对应的文件先写了, 目录位置微调都好办
web 改成 specification? |
嗯, web.md 本来就是 web specification |
usage 改成 guide? |
- Best Practice | ||
- Progressively-enhanced | ||
- How to write plugin | ||
- How to write framework |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
- How to write a plugin
- How to write a framework
加个 a ,哈哈
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
先合吧~ 后面再改~ 这2个还没想好是放到 Progressively-enhanced
里面还是单独一篇, 回头我写的时候再看
@atian25 I have time this weekend. Ping me when you reach to a logical milestone so that I can start working on it. |
@mattma In the coming days I had to focus on jsconf slide, the toc is almost ready, now need some guys to split @eggjs/core |
对文档的目录重新梳理了下, 大家看看. cc @eggjs/core
另外, 还有个比较纠结的地方:
WEB 规范
和 使用文档 有点重叠, 要看看怎么处理. @mattmaWeb Spec
Web Spec
的理解和实现后的使用文档.