Skip to content
This repository was archived by the owner on Nov 8, 2022. It is now read-only.

Commit 595ffa8

Browse files
mydearxymmydearxym
committed
docs: improve/add docs
1 parent 447c7da commit 595ffa8

11 files changed

+562
-16
lines changed

‎Makefile

+10-6
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
include Makefile.include.mk
22

33
help:
4+
$(call setup.help)
45
$(call launch.help)
56
$(call gen.help)
67
$(call commit.help)
@@ -13,10 +14,16 @@ help:
1314
$(call github.help)
1415
@echo "\n"
1516

16-
init:
17-
mix ecto.setup
17+
setup.help:
18+
$(call setup.help)
19+
@echo "\n"
20+
21+
setup:
22+
$(call setup.help)
23+
@echo "\n"
1824

19-
dep:
25+
setup.run:
26+
mix ecto.setup
2027
mix deps.get
2128
npm install # for commitizen
2229

@@ -26,9 +33,6 @@ build:
2633
format:
2734
mix format
2835

29-
dev:
30-
MIX_ENV=mock mix phx.server
31-
3236
launch.help:
3337
$(call launch.help)
3438
@echo "\n"

‎Makefile.include.mk

+13-4
Original file line numberDiff line numberDiff line change
@@ -37,11 +37,23 @@ define browse
3737
$(BROWSER_TOOL) "$(1)"
3838
endef
3939

40+
41+
define setup.help
42+
@echo "\n"
43+
@echo " [valid setup commands]"
44+
@echo " ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~"
45+
@echo " setup.run : setup the basic env for you, include 3-step"
46+
@echo " | 1. mix ecto.setup # create/migrate tables in db"
47+
@echo " | 2. mix deps.get # for insall deps"
48+
@echo " | 3. npm install # for commit-msg linter"
49+
@echo " ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~"
50+
endef
51+
4052
define launch.help
4153
@echo "\n"
4254
@echo " [valid launch commands]"
4355
@echo " ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~"
44-
@echo " dev : start phoenix server in local mock env"
56+
@echo " launch.mock : start server in mock(default) mode"
4557
@echo " | config locate in \"config/mock.exs\""
4658
@echo " ....................................................."
4759
@echo " launch.dev : start phoenix server in development env"
@@ -156,9 +168,6 @@ define test.help
156168
@echo " ....................................................."
157169
@echo " test.watch.bug : sometimes fails for unkown reason"
158170
@echo " ....................................................."
159-
@echo " test.db_reset : reset test database"
160-
@echo " | needed when add new migration"
161-
@echo " ....................................................."
162171
@echo " test.report : show test coverage status web page"
163172
@echo " ....................................................."
164173
@echo " test.report.text : show test coverage in terminal"

‎docs/development/console.zh-CN.md

+22-1
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,23 @@
11

2-
#### 中文文档出于时间关系尚未完善，欢迎 PR
2+
### console
3+
4+
Elixir/Phoenix 有和其他动态语言相似的 REPL 执行环境 - `iex`, 类似 Ruby 的 `irb`, Python
5+
中的 `ipython` 等等。你可以使用 `make console` 或者 `make console.help` 查看帮
6+
助:
7+
8+
```text
9+
10+
[valid console commands]
11+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
12+
console : run iex
13+
...................................
14+
console.dev : run iex in dev env
15+
...................................
16+
console.mock : run iex in mock env
17+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
18+
19+
```
20+
21+
注意: 原始的 iex 命令行工具功能较为单一， 所以这里的 console.* 命令在下层调用的加参数后的 iex 程序, 比如你运行 `make
22+
console.mock` , 在执行时会转换成 `MIX_ENV=mock iex --erl "-kernel shell_history
23+
enabled" -S mix`, 以支持命令历史等操作。

‎docs/development/generator.zh-CN.md

+21-1
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,22 @@
11

2-
#### 中文文档出于时间关系尚未完善，欢迎 PR
2+
### generator
3+
4+
帮助在开发时快速生成一些样板代码， 使用 `make gen` 或 `make gen.help` 查看帮助。
5+
6+
```text
7+
8+
[valid generators]
9+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
10+
gen.migration : generate migration fils
11+
| e.p : gen.migration arg="add_name_to_users"
12+
| note : need to run "make migrate" later
13+
..................................................................................
14+
gen.context : generate a new context
15+
| e.p: make gen.context Accounts Credential credentials
16+
email:string:unique user_id:references:users
17+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
18+
19+
```
20+
21+
22+

‎docs/development/intro.zh-CN.md

+141-1
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,142 @@
11

2-
#### 中文文档出于时间关系尚未完善，欢迎 PR
2+
受 [@tyrchen](https://github.com/tyrchen) 老师的 [code is law](https://zhuanlan.zhihu.com/p/36913380),
3+
启发，本项目使用类 unix 环境下最基础的 `make` 作为构建工具, 遵循统一清晰的命名规范，以便在前后端各个子项目
4+
间做到 `don't make me think` 的工作流程。 你可以在项目根目录执行 `make` 或 `make help` 查看帮助。
5+
6+
```text
7+
[valid launch commands]
8+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~"
9+
launch.mock : start server in mock(default) mode"
10+
| config locate in \"config/mock.exs\""
11+
....................................................."
12+
launch.dev : start phoenix server in development env"
13+
| config locate in \"config/dev.exs\""
14+
....................................................."
15+
launch.prod : start phoenix server in produnction env"
16+
| config locate in \"config/prod.exs\""
17+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~"
18+
19+
20+
[valid generators]
21+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
22+
gen.migration : generate migration fils
23+
| e.p : gen.migration arg="add_name_to_users"
24+
| note : need to run "make migrate" later
25+
..................................................................................
26+
gen.context : generate a new context
27+
| e.p: make gen.context Accounts Credential credentials
28+
email:string:unique user_id:references:users
29+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
30+
31+
32+
[valid commit commands]
33+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
34+
commit : commit changes follow convention
35+
| convention: AngularJS's commit message convention
36+
| link: https://github.com/commitizen/cz-cli
37+
| link: https://github.com/angular/angular.js/blob/master/DEVELOPERS.md#-git-commit-guidelines
38+
| require: npm install
39+
| require: npm -v > 5.2 to use npx
40+
| link: https://medium.com/@maybekatz/introducing-npx-an-npm-package-runner-55f7d4bd282b
41+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
42+
43+
44+
[valid release commands]
45+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
46+
release : release version by automatic CHANGELOG generation
47+
| link: https://github.com/conventional-changelog/standard-version
48+
| more:
49+
| npm run release -- --prerelease
50+
| npm run release -- --prerelease alpha
51+
.................................................................................
52+
release.master : release master branch
53+
.................................................................................
54+
release.dev : release dev branch
55+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
56+
57+
58+
[valid deploy commands]
59+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
60+
deploy.dev : pack & push code to aliyun for dev
61+
| need manually restart docker container on aliyun
62+
...............................................................
63+
deploy.prod : pack & push code to for produnction
64+
| need manually restart docker container on aliyun
65+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
66+
67+
68+
[valid console commands]
69+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
70+
console : run iex
71+
...................................
72+
console.dev : run iex in dev env
73+
...................................
74+
console.mock : run iex in mock env
75+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
76+
77+
78+
[valid test commands]
79+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
80+
test : run all the test then quit
81+
.....................................................
82+
test.watch : run all the test in watch mode
83+
.....................................................
84+
test.watch.wip : run @wip test in watch mode
85+
.....................................................
86+
test.db_reset : reset test database
87+
| needed when add new migration
88+
.....................................................
89+
test.report : show test coverage status web page
90+
.....................................................
91+
test.report.text : show test coverage in terminal
92+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
93+
94+
95+
[valid dashboard commands]
96+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
97+
dashboard.apollo : graphql api status provide by apollo engine
98+
| https://engine.apollographql.com/account/gh.mydearxym/services
99+
.................................................................................
100+
dashboard.aliyun : aliyun console
101+
| https://home.console.aliyun.com/new
102+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
103+
104+
105+
[valid ci commands]
106+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
107+
ci.build : browse travis status
108+
| https://travis-ci.org/coderplanets/coderplanets_server
109+
..........................................................................
110+
ci.coverage : browse test coveralls status
111+
| https://coveralls.io/github/coderplanets/coderplanets_server
112+
..........................................................................
113+
ci.codecov : browse test codecov status
114+
| https://codecov.io/gh/coderplanets/coderplanets_server
115+
..........................................................................
116+
ci.doc : browse doc coverage status
117+
| https://inch-ci.org/github/coderplanets/coderplanets_server
118+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
119+
120+
121+
[valid github commands]
122+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
123+
github.code : browse source code in github
124+
| https://github.com/coderplanets/coderplanets_server
125+
....................................................................................
126+
github.doc : browse repo docs in github
127+
| https://github.com/coderplanets/coderplanets_server/tree/dev/docs
128+
....................................................................................
129+
github.pr : browse PRs in github
130+
| https://github.com/coderplanets/coderplanets_server/pulls
131+
....................................................................................
132+
github.issue : browse issues in github
133+
| https://github.com/coderplanets/coderplanets_server/issues
134+
....................................................................................
135+
github.issue.new : create issue in github
136+
| https://github.com/coderplanets/coderplanets_server/issues/new
137+
....................................................................................
138+
github.app : github oauth status (need login)
139+
| https://github.com/settings/applications/689577
140+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
141+
```
142+

‎docs/development/linter.zh-CN.md

+5-1
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,6 @@
11

2-
#### 中文文档出于时间关系尚未完善，欢迎 PR
2+
### 关于提交 git commit
3+
4+
5+
6+
todo

‎docs/development/setup.md

+21
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
2+
### setup
3+
4+
use `make setup.help` or `make setup` for help。 make sure you know what you are
5+
doing, then run `make setup.run`。
6+
7+
```text
8+
9+
[valid setup commands]
10+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
11+
setup.run : setup the basic env for you, include 3-step
12+
| 1. mix ecto.setup # create/migrate tables in db
13+
| 2. mix deps.get # for insall deps
14+
| 3. npm install # for commit-msg linter
15+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
16+
17+
```
18+
19+
20+
> NOTE: this cmd will not install Elixir/Erlang for you。 make sure you have thoese tools before setup
21+

‎docs/development/setup.zh-CN.md

+20
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
2+
### 初始化
3+
4+
使用 `make setup.help` 或 `make setup` 查看项目初始化命令。 在确保你知道用法后运
5+
行 `make setup.run`, 该命令将自动帮你创建/迁移数据库表，安装依赖包等等。
6+
7+
```text
8+
9+
[valid setup commands]
10+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
11+
setup.run : setup the basic env for you, include 3-step
12+
| 1. mix ecto.setup # create/migrate tables in db
13+
| 2. mix deps.get # for insall deps
14+
| 3. npm install # for commit-msg linter
15+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
16+
17+
```
18+
19+
20+
> 注意: 该命令不会帮你安装 Elixir/Erlang 环境。 请确保你的机器上有上述开发环境。

0 commit comments

Comments
 (0)