89 lines
2.2 KiB
Markdown
89 lines
2.2 KiB
Markdown
# 开发手册编写规范
|
||
|
||
此开发文档，目标人群是初次接触PhalApi框架的开发同学，重点在于讲解如何使用PhalApi进行快速开发。文档应该简短明了，并辅以示例。
|
||
|
||
## 文档编写规范
|
||
|
||
为了能给开发同学提供简明、清晰、实用的技术开发文档，特此约定：
|
||
|
||
### 1、文件名
|
||
|
||
文档文件名字使用英文完整单词，分割符号为中横线。**不需要**编号，且**不建议**使用中文，避免难看且漫长的URL。例如：
|
||
```bash
|
||
# 错误的文件名
|
||
[1.1]-下载与安装.md
|
||
|
||
# 推荐的文件名
|
||
setup.md
|
||
```
|
||
|
||
### 2、文档模板格式
|
||
|
||
============================================
|
||
|
||
# 一级标题，章节标题
|
||
## 二级标题，小节标题
|
||
### 三级标题，各内容列表
|
||
#### 四级标题，尽量避免使用
|
||
|
||
> 温馨提示：一些注意事项，技巧，参与链接。
|
||
|
||
对于关键字可使用**加粗方式**进行强调。
|
||
|
||
============================================
|
||
|
||
### 3、代码风格
|
||
|
||
对于代码片段，应注明代码对应的开发语言，以便可以进行代码高亮 。例如：
|
||
```
|
||
```php
|
||
<?php
|
||
// 以下是php代码片段……
|
||
```
|
||
|
||
示例：
|
||
```php
|
||
<?php
|
||
$api = new PhalApi();
|
||
$rs = $api->response();
|
||
$rs->output();
|
||
```
|
||
|
||
如果需要说明代码文件路径，可以在首行注释说明，如：
|
||
```php
|
||
<?php
|
||
// 入口文件 ./Public/index.php
|
||
$api = new PhalApi();
|
||
$rs = $api->response();
|
||
$rs->output();
|
||
```
|
||
|
||
### 4、图片文件
|
||
|
||
关于图片，请统一存放在CDN，以便随处可访问并加快浏览速度。请使用[自助图片上传到七牛CDN](http://demo.phalapi.net/qiniu_upload.html)。
|
||
|
||
### 5、尽量使用短句
|
||
|
||
错误的写法：
|
||
```
|
||
这是一句非常非常非常非常非常非常非常非常非常非常非常非常非常非常非常非常非常非常长的句子。
|
||
```
|
||
|
||
推荐的写法：
|
||
```
|
||
这是一句非常长的句子，因为它真的非常非常长。
|
||
```
|
||
|
||
### 6、正文内容的标点符号，统一使用全角中文，非英文半角
|
||
|
||
错误的写法：
|
||
```
|
||
这里最后是一个英文半角的逗号,和一个英文半角的感叹号!
|
||
```
|
||
|
||
推荐的写法：
|
||
```
|
||
这里最后是一个中文全角的逗号，和一个中文全角的感叹号！
|
||
```
|
||
|