A standard style for README files
Your README file is normally the first entry point to your code. It should tell people why they should use your module, how they can install it, and how they can use it. Standardizing how you write your README makes creating and maintaining your READMEs easier. Great documentation takes work!
gantt
dateFormat YYYY-MM-DD
title Adding GANTT diagram functionality to mermaid
section A section
Completed task :done, des1, 2014-01-06,2014-01-08
Active task :active, des2, 2014-01-09, 3d
Future task : des3, after des2, 5d
Future task2 : des4, after des3, 5d
section Critical tasks
Completed task in the critical line :crit, done, 2014-01-06,24h
Implement parser and jison :crit, done, after des1, 2d
Create tests for parser :crit, active, 3d
Future task in critical line :crit, 5d
Create tests for renderer :2d
Add to mermaid :1d
section Documentation
Describe gantt syntax :active, a1, after des1, 3d
Add gantt diagram to demo page :after a1 , 20h
Add another diagram to demo page :doc1, after a1 , 48h
section Last section
Describe gantt syntax :after doc1, 3d
Add gantt diagram to demo page :20h
Add another diagram to demo page :48h
This repository contains:
- The specification for how a standard README should look.
- A link to a linter you can use to keep your README maintained (work in progress).
- A link to a generator you can use to create standard READMEs.
- A badge to point to this spec.
- Examples of standard READMEs - such as this file you are reading.
Standard Readme is designed for open source libraries. Although it’s historically made for Node and npm projects, it also applies to libraries in other languages and package managers.
graph LR
start[开始] --> input[输入A,B,C]
input --> conditionA{A是否大于B}
conditionA --> |YES|conditionC{A是否大于C}
conditionA -- NO --> conditionB{B是否大于C}
conditionC -- YES --> printA[输出A]
conditionC -- NO --> printC[输出C]
conditionB -- YES --> printB[输出B]
conditionB -- NO --> printC[输出C]
printA --> stop[结束]
printC --> stop
printB --> stop
Standard Readme started with the issue originally posed by @maxogden over at feross/standard in this issue, about whether or not a tool to standardize readmes would be useful. A lot of that discussion ended up in zcei's standard-readme repository. While working on maintaining the IPFS repositories, I needed a way to standardize Readmes across that organization. This specification started as a result of that.
Your documentation is complete when someone can use your module without ever having to look at its code. This is very important. This makes it possible for you to separate your module's documented interface from its internal implementation (guts). This is good because it means that you are free to change the module's internals as long as the interface remains the same.
Remember: the documentation, not the code, defines what a module does.
Writing READMEs is way too hard, and keeping them maintained is difficult. By offloading this process - making writing easier, making editing easier, making it clear whether or not an edit is up to spec or not - you can spend less time worrying about whether or not your initial documentation is good, and spend more time writing and using code.
By having a standard, users can spend less time searching for the information they want. They can also build tools to gather search terms from descriptions, to automatically run example code, to check licensing, and so on.
The goals for this repository are:
- A well defined specification. This can be found in the Spec document. It is a constant work in progress; please open issues to discuss changes.
- An example README. This Readme is fully standard-readme compliant, and there are more examples in the
example-readmesfolder. - A linter that can be used to look at errors in a given Readme. Please refer to the tracking issue.
- A generator that can be used to quickly scaffold out new READMEs. See generator-standard-readme.
- A compliant badge for users. See the badge.
graph LR
start[开始] --> input[输入A,B,C]
input --> conditionA{A是否大于B}
conditionA -- YES --> conditionC{A是否大于C}
conditionA -- NO --> conditionB{B是否大于C}
conditionC -- YES --> printA[输出A]
conditionC -- NO --> printC[输出C]
conditionB -- YES --> printB[输出B]
conditionB -- NO --> printC[输出C]
printA --> stop[结束]
printC --> stop
printB --> stop
sequenceDiagram
participant Alice
participant Bob
Alice->>John:hello John
loop healthcheck
John-->>John:fight against
end
Note right of John:rational
John->>Alice:great!
John->>Bob:how about you
Bob->>John:good!
- Enviroment
$ uname -a
Linux wtdcserver 5.4.0-73-generic #82~18.04.1-Ubuntu SMP Fri Apr 16 15:10:02 UTC 2021 x86_64 x86_64 x86_64 GNU/Linux
$ java -version
java version "13.0.1" 2019-10-15
Java(TM) SE Runtime Environment (build 13.0.1+9)
Java HotSpot(TM) 64-Bit Server VM (build 13.0.1+9, mixed mode, sharing)
$ gradle -version
------------------------------------------------------------
Gradle 7.0.2
------------------------------------------------------------
Build time: 2021-05-14 12:02:31 UTC
Revision: 1ef1b260d39daacbf9357f9d8594a8a743e2152e
Kotlin: 1.4.31
Groovy: 3.0.7
Ant: Apache Ant(TM) version 1.10.9 compiled on September 27 2020
JVM: 13.0.1 (Oracle Corporation 13.0.1+9)
OS: Linux 5.4.0-73-generic amd64
- Clone code and change directories
$ git clone https://gitee.com/dc-melo/standard-readme.git
OR
$ git clone https://github.com/DC-Melo/standard-readme.git
$ cd standard-readmeThis project uses node and npm. Go check them out if you don't have them locally installed.
$ npm install --global standard-readme-specThis is only a documentation package. You can print out spec.md to your console:
$ standard-readme-spec
# Prints out the standard-readme specTo use the generator, look at generator-standard-readme. There is a global executable to run the generator in that package, aliased as standard-readme.
If your README is compliant with Standard-Readme and you're on GitHub, it would be great if you could add the badge. This allows people to link back to this Spec, and helps adoption of the README. The badge is not required.
To add in Markdown format, use this code:
[](https://github.com/RichardLitt/standard-readme)
To see how the specification has been applied, see the example-readmes.
- Art of Readme - 💌 Learn the art of writing quality READMEs.
- open-source-template - A README template to encourage open-source contributions.
Feel free to dive in! Open an issue or submit PRs.
Standard Readme follows the Contributor Covenant Code of Conduct.
This project exists thanks to all the people who contribute.
MIT © DC-Melo王江
如果你喜欢我的项目，请在对应的项目右上角 "Star" 一下。你的支持是我最大的鼓励！ ^^ 你也还可以扫描下面的二维码，对作者进行打赏。
If you like my project, "Star" in the corresponding project right corner, please. Your support is my biggest encouragement! ^^ You can also scan the qr code below or Donate to this project using Paypal, donation to Author.
如果在捐赠留言中备注名称，将会被记录到列表中~ 如果你也是github开源作者，捐赠时可以留下github项目地址或者个人主页地址，链接将会被添加到列表中起到互相推广的作用
If you comment on the name in the donation message, it will be recorded in the list. ~If you are also an open source author of github, you can leave the GitHub project address or personal home page address when donating. Links will be added to the list to promote each other. 捐赠列表(Donation list)