diff --git a/07.md b/07.md index fc20f6999b9423396f02b38c0168509e7aa47727..d137f6178e31b2a64038145f3d0f4d0c7703625f 100644 --- a/07.md +++ b/07.md @@ -1,15 +1,80 @@ -## ------- - -### 1. - - - - - -### 相关链接 - -* [目录](readme.md) -* 下一章: [四、如何使用项目仓库?](04.md) -* 上一章: [二、“码云”网站的基本使用](02.md) - +## 七、为项目编写文本文档 +------ + +### 1. 什么是 README 文件 ? + +README 文件是让其他用户了解有关你的工作详情的一种快速简单的方式。 +在项目中至少拥有一个 README 文档是一个好主意,因为这是许多人第一次发现你的项目时会首先阅读的内容。 + +如果你需要挖掘项目更深层次的信息,可以用到Wiki。Wiki是一种在网络上开放且可供多人协同创作的超文本系统,Wiki站点可以有多人维护,每个人都可以发表自己的意见,或者对共同的主题进行扩展与探讨。(关于码云网站wiki的使用方法将在后面章节详细介绍) + +### 2. 编辑 README 文档 + +当我们按照前面文章的方法,通过 Fork 得到了一个与原始项目完全相同的项目仓库副本,我们就拥有了完全的管理权限,可以随意添加、删除文件,修改文件内容。 + +鼠标左键单击 README.md 文档,在文档标题的右上角单击 **编辑** 按钮,如下图所示: +![编辑按钮](https://images.gitee.com/uploads/images/2020/0218/011306_35022e62_5678580.jpeg "3.jpg") +> **注意:** 这里以编辑 README 文档为例,在实际使用中对于后缀为 **.md** 的文档均可以单击进行编辑、修改与完善,如下图所示: +> +![输入图片说明](https://images.gitee.com/uploads/images/2020/0218/012257_a3fb1568_5678580.jpeg "2.jpg") + +### 3. 格式化 README 文档 + +README 文档通常遵循一种格式,以便使开发人员可以立即定位到项目中最重要的部分。 + + **项目名称:** 你的项目名称是人们在滚动 README 文档时将看到的第一个内容,并且在创建 README 文档时已经包含在内。 + + **描述:** 项目的描述在下面。一个好的描述需要是清晰的,简短的和一针见血的。描述你的项目的重点,以及它的作用。 + + **目录:** (可选的 ->)包含一个目录可以让人们在一篇详细的 README 文档中快速导航。 + + **安装:** 有效的 README 文档的下一个部分是安装。它用于告诉其他用户如何在本地安装你的项目。(可选的 ->)包含一个 gif 动图以便别人可以更清楚该过程。 + + **用法:** 再下一个部分是用法,它用于指导其他用户在安装后将如何使用该项目。在这里,最好包括该项目启动后的屏幕截图。 + + **贡献:** 对于较大的项目来说,通常会有部分章节是概述如何参与项目的说明。有时,这是一个单独的文件。如果你有具体的偏好需求,请解释它们以便其他开发人员指导如何才能最好的参与到你的项目中来。 + + **名单:** 包括一个名单的部分,以突出显示和链接到你的项目的作者。 + +### 3. 文档的内容编写 + + **Markdown** 是一种可以使用普通文本编辑器编写的标记语言,通过简单的标记语法,它可以使普通文本内容具有一定的格式。Markdown的语法简洁明了、学习容易,而且功能比纯文本更强,因此我们通常采用它来写编写文档。 + +Markdown 语法的目标是:成为一种适用于网络的书写语言。 因此,Markdown是兼容Html,HTML 是一种发布的格式,Markdown 是一种书写的格式。就这样,Markdown 的格式语法只涵盖纯文本可以涵盖的范围。不在 Markdown 涵盖范围之内的标签,都可以直接在文档里面用 HTML 撰写。不需要额外标注这是 HTML 或是 Markdown;只要直接加标签就可以了。 + +关于Markdown的具体语法及原理,请查看 [Markdown语法及原理从入门到高级](https://blog.csdn.net/weixin_35073408/article/details/100586583?utm_source=app),学习 Markdown 一文,了解与掌握有关如何修改文件中的文本内容。 +* 如果你是自己新建的文档,不要忘记给你的文档命名,一般文本文档命名。 + +* 当然,你可以充分利用 **文档编辑的工具栏** ,就在正文上方,功能如我们平常使用的Word基本相同,具有 **粗体** 、 _斜体_ 、标题突出 +、插入链接、插入图片、插入表情、插入列表(分为有序列表和无序列表)、插入表格、插入代码、引用的基本功能,如图所示: +![文档编辑工具栏](https://images.gitee.com/uploads/images/2020/0218/104941_330274d5_5678580.jpeg "5.jpg") + +### 4. 确定并提交文本文档 + +(1) 当我们用 Markdown 的语法编辑好文档以后,想要预览效果如何,可以从 _文档编辑的工具栏_ 中选择 **眼睛** 按钮,或者利用快捷键 **“ctrl+P”** 预览文本编辑效果。 +(2) 在确定好自己编写的文本文档以后,就需要进行提交的工作,在文档编辑框下方, +* **提交信息:** 在 Git 中,每次提交代码,都要写 Commit message(提交说明),否则就不允许提交。这个操作将通过 git commit 完成。 +* **扩展信息:** 此处填写为什么修改,做了什么样的修改,以及开发者的思路等更详细的信息。 +* **目标分支:** 单击此处会出现下拉菜单,选择将文本提交至哪一个分支,如果没有新建分支的情况下,默认为 **master** 主分支。 +* **提交:** 单击提交按钮以后,你编辑好的文本文档就能够成功提交到fork过来的仓库中了! +如图所示: +![确定并提交文本文档](https://images.gitee.com/uploads/images/2020/0218/111943_0e08cce3_5678580.jpeg "6.jpg") + +### 5. 通过 Pull Request 提交合并请求 + +由于刚才编辑和修改的只是自己帐号下的项目仓库文件,而不是原始项目的仓库。如前文所述,[六、通过 Fork 参与项目](06.md)如果要将自己修改的文件上传到原始项目仓库,参与项目完善工作,需要通过 **Pull Requests** 进行操作,以便与原始仓库的文件进行 **更新与合并** 。 + +### 6. 更多 Markdown 语法举例 + +~~文字~~:文字加**删除线** + +符号 - 或 * ,连续3个及以上:**分割线** + +Markdown 允许段落内的强迫换行(插入换行符)。如果想要 **空一行** ,在插入处先按入两个以上的空格然后回车,即可。 + +### 相关链接 + +* [目录](readme.md) +* 下一章: [八、其它](08.md) +* 上一章: [六、通过 Fork 参与项目完善](06.md) + diff --git a/08.md b/08.md new file mode 100644 index 0000000000000000000000000000000000000000..e69de29bb2d1d6434b8b29ae775ad8c2e48c5391