如何规范写出 README 模板?

这篇具有很好参考价值的文章主要介绍了如何规范写出 README 模板?。希望对大家有所帮助。如果存在错误或未考虑完全的地方,请大家不吝赐教,您也可以点击"举报违法"按钮提交疑问。

README 标准是由 RichardLitt 发起,十多名开发者共同贡献完成的,在 GitHub 上有 1230+ Star:standard-readme

标准 README 实例:

  • standard-readme/tree/main/example-readmes
  • 奖励:实例

本文模板获取地址: README-Template


README 文件是人们通常最先看到的第一个东西。它应该告诉人们为什么要使用、如何安装、以及如何使用你的代码。README 文件标准化能够使得创建和维护 README 文件更加简单。毕竟,要写好一个文档不是那么容易的。

1. Sections

Title

Status: Required.

Requirements:

  • 标题必须与 repository、folder 和 package manager names 匹配 - 或者它可能有另一个相关的标题,repository、folder 和 package manager title 旁边以斜体和括号显示。例如:
# Standard Readme Style _(standard-readme)_

If any of the folder, repository, or package manager names do not match, there must be a note in the Long Description explaining why.

Suggestions:

  • Should be self-evident.

Banner

Status: Optional.

Requirements:

  • Must not have its own title.
  • Must link to local image in current repository.
  • Must appear directly after the title.

Badges

Status: Optional.

Requirements:

  • Must not have its own title.
  • Must be newline delimited.

Suggestions:

  • Use http://shields.io or a similar service to create and host the images.
    Add the Standard Readme badge.

Short Description

Status: Required.

Requirements:

  • Must not have its own title.
  • Must be less than 120 characters.
  • Must not start with >
  • Must be on its own line.
  • Must match the description in the packager manager’s description field.
  • Must match GitHub’s description (if on GitHub).

Suggestions:

  • Use gh-description to set and get GitHub description.
  • Use npm show . description to show the description from a local npm package.

Long Description

Status: Optional.

Requirements:

  • Must not have its own title.
  • If any of the folder, repository, or package manager names do not match, there must be a note here as to why. See Title section.

Suggestions:

  • If too long, consider moving to the Background section.

  • Cover the main reasons for building the repository.

  • "This should describe your module in broad terms, generally in just a few paragraphs; more detail of the module’s routines or methods, lengthy code examples, or other in-depth material should be given in subsequent sections.这应该广泛地描述你的模块,通常只有几个段落;关于模块的例程或方法、冗长的代码示例或其他深入材料的更多细节将在后续章节中给出。

Ideally, someone who’s slightly familiar with your module should be able to refresh their memory without hitting “page down”. As your reader continues through the document, they should receive a progressively greater amount of knowledge."理想情况下,稍微熟悉您的模块的人应该能够刷新他们的内存,而不需要点击“下一页”。当你的读者继续阅读文档时,他们会逐渐获得更多的知识。

Table of Contents

Status: Required; optional for READMEs shorter than 100 lines.

Requirements:

  • Must link to all Markdown sections in the file. 必须链接到文件中的所有 Markdown 部分。
  • Must start with the next section; do not include the title or Table of Contents headings. 必须从下一节开始;不要包括标题或目录标题。
  • Must be at least one-depth: must capture all ## headings.

Suggestions:

  • May capture third and fourth depth headings. If it is a long ToC, these are optional.

Security

Status: Optional.

Requirements:

  • May go here if it is important to highlight security concerns. Otherwise, it should be in Extra Sections.

Background

Status: Optional.

Requirements:

  • Cover motivation.
  • Cover abstract dependencies.
  • Cover intellectual provenance: A See Also section is also fitting.

Install

Status: Required by default, optional for documentation repositories.

Requirements:

  • Code block illustrating how to install.

Subsections:

  • Dependencies. Required if there are unusual dependencies or dependencies that must be manually installed. 如果存在不寻常的依赖项或必须手动安装的依赖项,则必需。

Suggestions:

  • Link to prerequisite sites for programming language: npmjs, godocs, etc.
  • Include any system-specific information needed for installation. 包括安装所需的任何系统特定信息。
  • An Updating section would be useful for most packages, if there are multiple versions which the user may interface with. 如果用户可能接触到多个版本的包,则 update 部分对于大多数包都很有用。

Usage

Status: Required by default, optional for documentation repositories.

Requirements:

  • Code block illustrating common usage. 说明常用用法的代码块。
  • If CLI compatible, code block indicating common usage. 如果兼容CLI,表示常用的代码块。
  • If importable, code block indicating both import functionality and usage. 如果可导入,则表示导入功能和使用情况的代码块。

Subsections:

  • CLI. Required if CLI functionality exists.

Suggestions:

  • Cover basic choices that may affect usage: for instance, if JavaScript, cover promises/callbacks, ES6 here. 涵盖可能影响使用的基本选择:例如,如果是 JavaScript,请在​​此处涵盖 promises/callbacks、ES6。
  • If relevant, point to a runnable file for the usage code. 如果相关,指向使用代码的可运行文件。

Extra Sections

Status: Optional.

Requirements:

  • None.

Suggestions:

  • This should not be called Extra Sections. This is a space for 0 or more sections to be included, each of which must have their own titles.
  • This should contain any other sections that are relevant, placed after Usage and before API.
  • Specifically, the Security section should be here if it wasn’t important enough to be placed above.

API

Status: Optional.

Requirements:

  • Describe exported functions and objects. 描述导出的函数和对象。

Suggestions:

  • Describe signatures, return types, callbacks, and events. 描述签名、返回类型、回调和事件。
  • Cover types covered where not obvious. 覆盖不明显的覆盖类型。
  • Describe caveats. 描述说明。
  • If using an external API generator (like go-doc, js-doc, or so on), point to an external API.md file. This can be the only item in the section, if present. 如果使用外部API生成器(如go-doc, js-doc等),则指向外部“API”。md的文件。如果存在,这可以是节中唯一的项。

Thanks

Status: Optional.

Requirements:

  • Must be called Thanks, Credits or Acknowledgements.

Suggestions:

  • State anyone or anything that significantly helped with the development of your project.
  • State public contact hyper-links if applicable.

Contributing

Status: Required.

Requirements:

  • State where users can ask questions.
  • State whether PRs are accepted.
  • List any requirements for contributing; for instance, having a sign-off on commits.

Suggestions:

  • Link to a CONTRIBUTING file – if there is one.
  • Be as friendly as possible.
  • Link to the GitHub issues.
  • Link to a Code of Conduct. A CoC is often in the Contributing section or document, or set elsewhere for an entire organization, so it may not be necessary to include the entire file in each repository. However, it is highly recommended to always link to the code, wherever it lives.
  • A subsection for listing contributors is also welcome here.

License

Status: Required.

Requirements:

  • State license full name or identifier, as listed on the SPDX license list. For unlicensed repositories, add UNLICENSED. For more details, add SEE LICENSE IN <filename> and link to the license file. (These requirements were adapted from npm).
  • State license owner.
  • Must be last section.

Suggestions:

  • Link to longer License file in local repository.

Definitions

These definitions are provided to clarify any terms used above.

  • Documentation repositories: Repositories without any functional code. For instance, RichardLitt/knowledge.

2. Chicken-Swarm-Optimization

源地址: https://github.com/decipher07/Chicken-Swarm-Optimization
readme模板,其他内容,Git 相关,javascript,github,前端

2. pyswarm

源地址: https://github.com/tisimst/pyswarm

https://pythonhosted.org/pyswarm/
readme模板,其他内容,Git 相关,javascript,github,前端

3. minimal-readme.md

源地址: standard-readme/blob/main/example-readmes/minimal-readme.md
readme模板,其他内容,Git 相关,javascript,github,前端

4. 模板四

readme模板,其他内容,Git 相关,javascript,github,前端

4. 王者版

readme模板,其他内容,Git 相关,javascript,github,前端

# Title

[![license](https://camo.githubusercontent.com/4738d430387c93da0d49ef0428a7c7ddae18e81eaff99a014996d4f6b30fd3ef/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6c6963656e73652f3a757365722f3a7265706f2e737667)](https://github.com/RichardLitt/standard-readme/blob/main/example-readmes/LICENSE) [![standard-readme compliant](https://camo.githubusercontent.com/f116695412df39ab3c98d8291befdb93af123f56aecc79fff4b20c410a5b54c7/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f726561646d652532307374796c652d7374616e646172642d627269676874677265656e2e7376673f7374796c653d666c61742d737175617265)](https://github.com/RichardLitt/standard-readme)

This is an example file with maximal choices selected.

This is a long description.

## Table of Contents

- [Install](#Install)
- [Configuration](#Configuration)(可选)
- [Usage](#Usage)
- [API](#API)
- [Contributing](#Contributing)
- [License](#License)

## Install

Using [npm](https://www.npmjs.org/), just run the following command:

\```
npm install box-intersect
\```

This module works in any reasonable CommonJS environment, such as browsersify, iojs or node.js.

## Configuration

## API

## Contributing

## License

5. 终极版

readme模板,其他内容,Git 相关,javascript,github,前端

# Title

[![license](https://camo.githubusercontent.com/4738d430387c93da0d49ef0428a7c7ddae18e81eaff99a014996d4f6b30fd3ef/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6c6963656e73652f3a757365722f3a7265706f2e737667)](https://github.com/RichardLitt/standard-readme/blob/main/example-readmes/LICENSE) [![standard-readme compliant](https://camo.githubusercontent.com/f116695412df39ab3c98d8291befdb93af123f56aecc79fff4b20c410a5b54c7/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f726561646d652532307374796c652d7374616e646172642d627269676874677265656e2e7376673f7374796c653d666c61742d737175617265)](https://github.com/RichardLitt/standard-readme)

## About The Project

This is an example file with maximal choices selected.

This is a long description.


### Built With

Built Using Languages and Libraries Listed Below 
* [Python](https://docs.python.org/3/)
* [Java](https://docs.oracle.com/en/java/)
* [numpy](https://numpy.org/devdocs/)
* [sklearn](https://scikit-learn.org/stable/)


Or in tabular form

| environment | version   |
| ----------- | --------- |
| Python      | 3.7 ~ 3.8 |
| Java        |           |
| numpy       |           |
| sklearn     |           |


## Table of Contents

- [Getting Started](#Getting Started)

  - [Install](#Install)

  - [Configuration](#Configuration)**(可选)**

  - [Usage](#Usage)

- [API](#API)

- [Contributing](#Contributing)

- [License](#License)


## Getting Started

### Install

Using [npm](https://www.npmjs.org/), just run the following command:

\```
npm install box-intersect
\```

This module works in any reasonable CommonJS environment, such as browsersify, iojs or node.js.


### Configuration


### Usage


## API


## Contributing


## License

References

[1] 编写规范的readme文件

[2] 我们应该如何书写README及文档

[3] 如何写好Github中的readme?

[4] README.md文件的必要性

[5] 如何为开发项目编写规范的README文件(windows),此文详解文章来源地址https://www.toymoban.com/news/detail-672957.html

到了这里,关于如何规范写出 README 模板?的文章就介绍完了。如果您还想了解更多内容,请在右上角搜索TOY模板网以前的文章或继续浏览下面的相关文章,希望大家以后多多支持TOY模板网!

本文来自互联网用户投稿,该文观点仅代表作者本人,不代表本站立场。本站仅提供信息存储空间服务,不拥有所有权,不承担相关法律责任。如若转载,请注明出处: 如若内容造成侵权/违法违规/事实不符,请点击违法举报进行投诉反馈,一经查实,立即删除!

领支付宝红包 赞助服务器费用

相关文章

  • SimpleSniffer—ReadMe

    AppWizard has created this SimpleSniffer application for you. This application not only demonstrates the basics of using the Microsoft Foundation classes but is also a starting point for writing your application. AppWizard为您创建了这个SimpleSniffer应用程序。 此应用程序不仅演示了使用 Microsoft 基础课程的基础知识但也是编写应

    2024年02月08日
    浏览(26)
  • README

    简介 Markdown 是一种轻量级标记语言,它允许人们使用易读易写的纯文本格式编写文档。 应用 当前许多网站都广泛使用 Markdown 来撰写帮助文档或是用于论坛上发表消息。例如:GitHub、简书、知乎等 编辑器 推荐使用 Typora ,官网:https://typora.io/ 什么是徽章 徽章是一种小巧精美

    2024年02月09日
    浏览(30)
  • GitHub 仓库的 README 直接播放视频

    GitHub 仓库的 README 文件,现在可以直接播放视频 上传超过10MB的视频会提示报错   https://user-images.githubusercontent.com … 1dc0b4888249.mp4  

    2024年02月09日
    浏览(41)
  • 【Ubuntu】 Github Readme导入GIF

    (1)直接转换命令: (2) 带参数命令: 参数说明: 在本地项目文件夹中打开README.md文件,然后将gif链接添加进去,至于添加的位置,我们想在哪个位置展示该gif图片就插入在哪个位置即可, 添加gif图片的代码按照以下格式构成: 然后再push即可

    2024年04月15日
    浏览(27)
  • 读程序员的README笔记06_测试(上)

    4.2.3.1. 消除外部依赖性可以使单元测试快速而集中 4.5.3.1. 压力测试可暴露系统的负载能力究竟有多大,以及在过度负载下会发生什么状况 4.6.3.1. ISO认证审核委员会要求提供需求和相应的测试文件证据 5.2.1.1. 管理测试的setup和teardown 5.2.1.2. 管理测试执行和编排 5.2.1.2.1. 可

    2024年02月05日
    浏览(46)
  • GitHub中readme.md文件的编辑和使用

    GitHub中readme.md文件的编辑和使用 | YuuiChung\\\'s Blog GitHub - guodongxiaren/README: README文件语法解读,即Github Flavored Markdown语法介绍  

    2024年02月13日
    浏览(37)
  • 读程序员的README笔记03_变更代码

    2.2.1.1. 定义变更点 2.2.1.2. 寻找测试点 2.2.1.3. 打破依赖关系 2.2.1.4. 编写测试 2.2.1.5. 进行修改和重构 2.2.2.1. 如果需要的话,为了让测试成为可能,可以对代码进行重构 2.2.2.2. 针对现有的软件行为也要添加测试用例 2.2.2.3. 一旦竖起栅栏,你的修改点周围的区域就得到了很

    2024年02月05日
    浏览(67)
  • 读程序员的README笔记09_代码评审

    4.4.1.1. walk-through 4.4.1.2. 一种面对面的会议,开发人员在会上共享他们的屏幕,并引导队友了解正在进行的修改内容 4.4.1.3. 是启发想法和让你的团队适应代码修改的好方法 5.1.2.1. 如果紧急度不明确,请询问提交者 5.4.4.1. SQL注入攻击、敏感数据泄露和跨站脚本攻击的漏洞

    2024年02月05日
    浏览(50)
  • 读程序员的README笔记07_测试(下)

    2.5.2.1. 首先应该关注代码中的高风险的区域 2.5.2.2. 那些低风险或被废弃的代码并不值得测试 3.2.1.1. 如果网络出现问题,那么测试也会失败 3.5.2.1. 使用常数种子的随机数生成器的测试将总是通过或总是失败 3.7.3.1. 注入式时间戳将让你使用模拟来精确控制测试中的时间流逝

    2024年02月05日
    浏览(47)
  • 读程序员的README笔记08_依赖管理

    2.6.1.1. 版本不应该被重复使用 2.6.1.2. 永远不要在现有版本下重新发布更改的代码 2.6.2.1. 版本应该帮助人们和工具对版本的优先顺序进行推断 2.6.3.1. 版本信息区分了预先发布的代码和已发布的代码,将构建流水号与构件相关联,并设置了稳定性和兼容性的合理预期 6.2.5.1

    2024年02月05日
    浏览(48)

觉得文章有用就打赏一下文章作者

支付宝扫一扫打赏

博客赞助

微信扫一扫打赏

请作者喝杯咖啡吧~博客赞助

支付宝扫一扫领取红包,优惠每天领

二维码1

领取红包

二维码2

领红包