Github README.md编写指南

分手后的思念是犯贱 2022-03-21 02:52 344阅读 0赞

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

# 内容 #

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

README.md最好要包含：

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

# 展示形式 #

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

## 基本内容 ##

下面是README.md子版块内容示例，它基本呈现了编写某板块内容的几个要素及其展示形式：  
![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2JhaWR1XzI2NjQ2MTI5_size_16_color_FFFFFF_t_70_pic_center]

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

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的地址既能引用网络上的图片，也可以用本项目内的图片。  
![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2JhaWR1XzI2NjQ2MTI5_size_16_color_FFFFFF_t_70]

## 徽章 ##

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

[![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](/images/20220321/6c4b006b454d42a3a245d73a9169bbe8.png)](https://travis-ci.org/Microsoft/MMdnn)

## 表情 ##

只要添加特定的前后带有冒号的字符串，就能出现相应表情。可以参考[github emoji][]  
![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2JhaWR1XzI2NjQ2MTI5_size_16_color_FFFFFF_t_70 1]

## 表格 ##

如果想要直观而整洁地展示项目所支持的功能、功能对比、历史版本对比等，表格是一个不错的形式。  
![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2JhaWR1XzI2NjQ2MTI5_size_16_color_FFFFFF_t_70 2]

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

[MMdnn]: https://github.com/Microsoft/MMdnn/blob/master/README.md
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2JhaWR1XzI2NjQ2MTI5_size_16_color_FFFFFF_t_70_pic_center]: /images/20220321/f378c53214b44cad8dc279dc1a1113e4.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2JhaWR1XzI2NjQ2MTI5_size_16_color_FFFFFF_t_70]: /images/20220321/480c58ae28af445f967b008e0f8e8163.png
[PyPi Version]: https://img.shields.io/pypi/v/mmdnn.svg
[PyPi Version 1]: https://pypi.org/project/mmdnn/
[License]: https://img.shields.io/badge/license-MIT-blue.svg
[Linux]: /images/20220321/6c4b006b454d42a3a245d73a9169bbe8.png
[Linux 1]: https://travis-ci.org/Microsoft/MMdnn
[github emoji]: https://segmentfault.com/a/1190000009649780
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2JhaWR1XzI2NjQ2MTI5_size_16_color_FFFFFF_t_70 1]: /images/20220321/b4003da4b9d7410c9962366768651a4d.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2JhaWR1XzI2NjQ2MTI5_size_16_color_FFFFFF_t_70 2]: /images/20220321/b46fe7a53736479082f85a05b37c3030.png