您的位置: 首页  >  文章  >  Github README.md编写指南

Github README.md编写指南

分类: 文章 • 2024-10-12 22:06:51

以MMdnn项目为例，总结开源项目README.md的一般编写套路。从内容和展示形式两方面进行说明。

内容

README.md最好要包含：

  • 项目名称及简介
  • 项目特点
  • 项目安装指南
  • 项目功能及使用指南
  • 使用范例
  • 其他说明

展示形式

基本内容

下面是README.md子版块内容示例，它基本呈现了编写某板块内容的几个要素及其展示形式：
Github README.md编写指南

  • 标题：项目名称采用一级标题，因此其子块内容多采用二级、三级甚至更低级别
  • 内容：不同段落之间通过空行分割，内容如果在逻辑上存在关联可以用列表来呈现，为内容添加外部链接以查找关联知识

markdown示例：

## Related Projects

- Open Platform for AI (OpenPAI)
- Neural Network Intelligence (NNI)

[Open Platform for AI (OpenPAI)](https://github.com/Microsoft/pai)

代码

如果子版块内容包含代码，如安装指南中的安装代码，可以在代码块前后分别加上三个反引号，并在代码块之前的三个反引号之后添加代码所属语言，如bash、shell、js等：

pip install mmdnn

图片

README.md中的图片可以用img标签引入，通过src的地址既能引用网络上的图片，也可以用本项目内的图片。
Github README.md编写指南

<img src="https://raw.githubusercontent.com/Microsoft/MMdnn/master/docs/supported.jpg" width="633" >

徽章

下面这几个很酷的shields | badge | travis-ci能让项目基础环境信息、编译、测试信息等一目了然，他们都是在特定网站生成后以外链的方式引入的，结合markdown添加外链，就能实现点击徽章后跳转到特定网站：
Github README.md编写指南Github README.md编写指南Github README.md编写指南

[![PyPi Version](https://img.shields.io/pypi/v/mmdnn.svg)](https://pypi.org/project/mmdnn/)
[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![Linux](https://travis-ci.org/Microsoft/MMdnn.svg?branch=master)](https://travis-ci.org/Microsoft/MMdnn)

表情

只要添加特定的前后带有冒号的字符串，就能出现相应表情。可以参考github emoji
Github README.md编写指南

表格

如果想要直观而整洁地展示项目所支持的功能、功能对比、历史版本对比等，表格是一个不错的形式。
Github README.md编写指南

Models | Caffe | Keras | TensorFlow | CNTK | MXNet | PyTorch  | CoreML | ONNX
:-----:|:-----:|:-----:|:----------:|:----:|:-----:|:--------:|:------:|:-----:|
[VGG 19](https://arxiv.org/abs/1409.1556.pdf) | √ | √ | √ | √ | √ | √ | √ | √
[Inception V1](https://arxiv.org/abs/1409.4842v1) | √ | √ | √ | √ | √ | √ | √ | √
[Inception V3](https://arxiv.org/abs/1512.00567)  | √ | √ | √ | √ | √ | √ | √ | √
[Inception V4](https://arxiv.org/abs/1512.00567)  | √ | √ | √ | o | √ | √ | √ | √
[ResNet V1](https://arxiv.org/abs/1512.03385)                               |   ×   |   √   |     √      |   o  |   √   |    √ | √ | √
[ResNet V2](https://arxiv.org/abs/1603.05027)                               |   √   |   √   |     √      |   √  |   √   | √ | √ | √
[MobileNet V1](https://arxiv.org/pdf/1704.04861.pdf)                        |   ×   |   √   |     √      |   o  |   √   |    √       | √ | √ | √
[MobileNet V2](https://arxiv.org/pdf/1704.04861.pdf)                        |   ×   |   √   |     √      |   o  |   √   |    √       | √ | √ | √
[Xception](https://arxiv.org/pdf/1610.02357.pdf)                            |   √   |   √   |     √      |   o  |   ×   |    √ | √ | √ | √
[SqueezeNet](https://arxiv.org/pdf/1602.07360)                              |   √   |   √   |     √      |   √  |   √   |    √ | √ | √ | √
[DenseNet](https://arxiv.org/abs/1608.06993)                                |   √   |   √   |     √      |   √  |   √   |    √       | √ | √
[NASNet](https://arxiv.org/abs/1707.07012)                                  |   x   |   √   |     √      |   o  |   √   | √ | √ | x
[ResNext](https://arxiv.org/abs/1611.05431)                                 |   √   |   √   |     √      |   √  |   √   | √ | √ | √ | √ | √
[voc FCN](https://people.eecs.berkeley.edu/~jonlong/long_shelhamer_fcn.pdf) |       |       |     √      |   √  |       |
Yolo3

相关推荐