GitHub（十一）：在 GitHub 上为你的项目写文档

ゝ一世哀愁。 2022-03-26 10:46 1174阅读 0赞

# Documenting your projects on GitHub #

原文链接 -> [传送门][Link 1]

好的文档是任何项目成功的关键。保持文档可访问能够使人们了解一个项目；使其易于更新以确保文档与项目紧密关联。

记录项目的两种常见方法是 README 文件和 wikis：

*  README 文件是让其他用户了解有关你的工作详情的一种快速简单的方式。
 *  GitHub 上的 wikis 帮助你以有用的方式提供关于项目更深层次的信息。

在项目中至少拥有一个 README 文档是一个好主意，因为这是许多人第一次发现你的项目时会首先阅读的内容。

--------------------

## **创建你的 README 文档** ##

当你通过 GitHub 创建一个新的仓库时，请选择“Initialize this repository with a README”（除非你计划导入现有的仓库）。

![232858u1zi26jiqiwsqujz.png][]

您的README.md文件现在可以在您的全新存储库中进行编辑。 您的项目名称在顶部，后面是您在创建存储库时选择包括的任何说明。 README易于修改，无论是在GitHub上还是本地。 查看Mastering Markdown指南，了解有关如何修改文件中的文本的更多信息。

现在，可以在你全新的仓库中编辑 README.md 文件。你的项目名称位于顶部，随后是你在创建仓库时选择包含的任何说明。无论是[在 Github 上][Github]还是本地，README 文档都易于修改。请查看 [GitHub（十）：掌握 Markdown][GitHub_ Markdown] 一文，了解有关如何修改文件中的文本内容。

--------------------

**格式化你的 README 文档**

README 文档通常遵循一种格式，以便使开发人员可以立即定位到项目中最重要的部分。

**项目名称：**你的项目名称是人们在滚动 README 文档时将看到的第一个内容，并且在创建 README 文档时已经包含在内。

**描述：**项目的描述在下面。一个好的描述需要是清晰的，简短的和一针见血的。描述你的项目的重点，以及它的作用。

**目录：**（可选的 ->）包含一个目录可以让人们在一篇详细的 README 文档中快速导航。

**安装：**有效的 README 文档的下一个部分是安装。它用于告诉其他用户如何在本地安装你的项目。（可选的 ->）包含一个 gif 动图以便别人可以更清楚该过程。

**用法：**再下一个部分是用法，它用于指导其他用户在安装后将如何使用该项目。在这里，最好包括该项目启动后的屏幕截图。

**贡献：**对于较大的项目来说，通常会有部分章节是概述如何参与项目的说明。有时，这是一个单独的文件。如果你有具体的偏好需求，请解释它们以便其他开发人员指导如何才能最好的参与到你的项目中来。要详细了解如何帮助他人参与项目，请查看这篇指南（设置仓库参与者的指针）-> [传送门][Link 2]。

**名单：**包括一个名单的部分，以突出显示和链接到你的项目的作者。

License: Finally, include a section for the license of your project. For more information on choosing a license, check out GitHub’s licensing guide!

**许可证：**最后，将许可证也一并包含到你的项目中。有关选择许可证的更多信息，请查看 GitHub 的许可指南 -> [传送门][Link 3]

你的 README 文档应该仅包含开发人员开始使用和参与你的项目所需的信息。然而较长的文档比较适合放在 wikis，如下所述。

--------------------

## **创建你的 wiki** ##

GitHub 上的每个仓库都有一个 wiki。在创建仓库之后，你可以通过侧边栏导航设置包含的 wiki。启动 wiki 只需点击 wiki 按钮即可创建第一个页面。

![022124lotgcn2vez5v3oqe.png][]

--------------------

## **添加内容** ##

wiki 内容被设计为很容易编辑的形式。你只需要单击位于页面右上角的“Edit”按钮，即可在任何 wiki 页面上添加或更改内容。这个步骤打开了 wiki 的编辑器。

![024353j4lui3p747bdpyel.png][]

Wiki 页面可以用 GitHub Markup 支持的任意格式编写。使用编辑器中的下拉菜单，你可以选择 wiki 的格式，然后使用 wiki 工具栏在页面上创建和输入内容。wiki 还可以选择包括自定义页脚，你可以在其中列出项目的联系人详细信息或许可证信息。

GitHub 跟踪对你的 wiki 中的每个页面所做的更改。在网页标题的下方，你可以看到最近进行过编辑的用户，还有提交到网页的次数。点击此信息将跳转到历史记录的完整页面，你可以比较修订内容或查看随时间变化的详细列表。

--------------------

## **添加页面** ##

你可以通过点击右上角的添加新页面为你的 wiki 添加页面。默认情况下，你创建的每个页面都会自动包含在 wiki 的侧边栏中，并按字母顺序列出。

![032454d5822q58s533828f.png][]

你也可以通过点击“Add custom sidebar”链接将自定义侧边栏添加到 wiki。自定义侧边栏内容可以包括文本，图像和链接。

注意：名称为“Home”的页面是你的 wiki 入口页面。如果缺少它，将显示自动生成的目录代替。

--------------------

**语法高亮**

Wiki pages support automatic syntax highlighting of code for a wide range of languages by using the following syntax:

wiki 页面通过使用以下语法，支持针对各种语言的代码的自动语法高亮显示：

```ruby
      def foo
        puts 'bar'
      end
    ```

代码块必须以三个反引号（\`）开始，（可选的 ->）跟该块代码所属语言的名称。有关可以语法高亮显示的语言列表，请参阅 -> [传送门][Link 4]。

代码块内容的缩进与开头反引号相同的级别。代码块必须以三个反引号结束，缩进与开头反引号相同的级别。

--------------------

## **你成功了！** ##

你已经学会了一项新技能，它指导你如何最好地与其余的 GitHub 社区分享你的工作。无论你的项目是否大到需要拥有自己的 wiki，或者你才刚刚开始，并建立一个清晰、简明的 README 文档。

To read more on the topics covered in this article, our guides for creating a new repository, editing files in your repository, setting guidelines for repository contributors and choosing a license are great places to start. Otherwise, check out some other GitHub Guides to keep learning.

要阅读更多关于本文所涵盖的主题，可以参考[创建新的仓库][Link 5]，[编辑仓库中的文件][Github]，[设置仓库贡献者的准则][Link 2]和[选择许可证][Link 3]都是很好的开始。否则，请查看一些其他 GitHub 指南以继续学习。

Finally, if you’re interested in building a documentation site for your project, we recommend using GitHub Pages.

最后，如果你有兴趣为你的项目构建文档站点，我们建议使用 [GitHub Pages][]。

[Link 1]: https://guides.github.com/features/wikis
[232858u1zi26jiqiwsqujz.png]: /images/20220326/62b7556f34104131af7967527e8b2227.png
[Github]: https://help.github.com/articles/editing-files-in-your-repository
[GitHub_ Markdown]: https://blog.csdn.net/qq_41556318/article/details/86515729
[Link 2]: https://help.github.com/articles/setting-guidelines-for-repository-contributors
[Link 3]: https://choosealicense.com/
[022124lotgcn2vez5v3oqe.png]: /images/20220326/ee3b78ff93c0464baf0ce7450e438df1.png
[024353j4lui3p747bdpyel.png]: /images/20220326/def934818a6545a995f01e9bf5c31d16.png
[032454d5822q58s533828f.png]: /images/20220326/ac14bf3db2bf4ff08d107d9d60859628.png
[Link 4]: http://pygments.org/docs/lexers
[Link 5]: https://help.github.com/articles/creating-a-new-repository
[GitHub Pages]: https://pages.github.com/