Compare commits
No commits in common. "master" and "feature/linter" have entirely different histories.
master
...
feature/li
3
LICENSE
3
LICENSE
@ -1,6 +1,6 @@
|
|||||||
The MIT License (MIT)
|
The MIT License (MIT)
|
||||||
|
|
||||||
Copyright (c) 2017-2019 Richard Littauer
|
Copyright (c) 2015 IPFS
|
||||||
|
|
||||||
Permission is hereby granted, free of charge, to any person obtaining a copy
|
Permission is hereby granted, free of charge, to any person obtaining a copy
|
||||||
of this software and associated documentation files (the "Software"), to deal
|
of this software and associated documentation files (the "Software"), to deal
|
||||||
@ -19,3 +19,4 @@ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|||||||
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
||||||
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
||||||
SOFTWARE.
|
SOFTWARE.
|
||||||
|
|
||||||
|
|||||||
114
README.cn.md
114
README.cn.md
@ -1,114 +0,0 @@
|
|||||||
# 标准 Readme
|
|
||||||
|
|
||||||
[](https://github.com/RichardLitt/standard-readme)
|
|
||||||
|
|
||||||
标准 Readme 样式
|
|
||||||
|
|
||||||
README 文件是人们通常最先看到的第一个东西。它应该告诉人们为什么要使用、如何安装、以及如何使用你的代码。README 文件标准化能够使得创建和维护 README 文件更加简单。毕竟，要写好一个文档不是那么容易的。
|
|
||||||
|
|
||||||
本仓库包含以下内容：
|
|
||||||
|
|
||||||
1. 一个标准的 README 文件应该是什么样子的[规范](spec.md)。
|
|
||||||
2. 一个用于维护 README 文件的语法提示工具的链接 ([正在进行中](https://github.com/RichardLitt/standard-readme/issues/5))。
|
|
||||||
3. 一个创建标准 README 的[生成器](https://github.com/RichardLitt/generator-standard-readme)。
|
|
||||||
4. 一个指向该规范的[徽章](#徽章)。
|
|
||||||
5. [标准 README 的实例](example-readmes/) - 比如你正在读的这个文件。
|
|
||||||
标准 Readme 是为了开源组件设计的。尽管它的[背景](#背景)是为了服务于 Node 和 npm 项目, 它同时也可以应用到其他编程语言和包管理器中去。
|
|
||||||
|
|
||||||
## 内容列表
|
|
||||||
|
|
||||||
- [背景](#背景)
|
|
||||||
- [安装](#安装)
|
|
||||||
- [使用说明](#使用说明)
|
|
||||||
- [生成器](#生成器)
|
|
||||||
- [徽章](#徽章)
|
|
||||||
- [示例](#示例)
|
|
||||||
- [相关仓库](#相关仓库)
|
|
||||||
- [维护者](#维护者)
|
|
||||||
- [如何贡献](#如何贡献)
|
|
||||||
- [使用许可](#使用许可)
|
|
||||||
|
|
||||||
## 背景
|
|
||||||
|
|
||||||
`标准 Readme` 最开始因为 [@maxogden](https://github.com/maxogden) 在项目 [feross/standard](https://github.com/feross/standard) 的[这个 Issue](https://github.com/feross/standard/issues/141) 中提出，是否标准化 README 会有助于帮助大家。很多人在仓库 [zcei's standard-readme](https://github.com/zcei/standard-readme/issues/1) 就这个想法进行了讨论。在我维护仓库 [IPFS](https://github.com/ipfs) 的时候，我需要在这个组织中推广标准化的 Readme，因此这个项目也就从这开始了。
|
|
||||||
|
|
||||||
> 如果你的文档是完整的，那么使用你代码的人就不用再去看代码了。这非常的重要。它使得你可以分离接口文档与具体实现。它意味着你可修改实现的代码而保持接口与文档不变。
|
|
||||||
|
|
||||||
> 请记住：是文档而非代码，定义了一个模块的功能。
|
|
||||||
|
|
||||||
—— [Ken Williams, Perl Hackers](http://mathforum.org/ken/perl_modules.html#document)
|
|
||||||
|
|
||||||
写 README 从某种程度上来说相当不易，一直维护下去更是难能可贵。如果可以减少这个过程，则可以让写代码与修改代码更容易，使得是否在说明中指明一处需改有无必要更加清楚，你可以花费更少的时间来考虑是否你最初的文档是否需要更新，你可以分配更多的时间来写代码而非维护文档。
|
|
||||||
|
|
||||||
同时，标准化在某些别的地方也有好处。有了标准化，用户就可以花费更少的时间来搜索他们需要的信息，他们同时可以做一个工具来从描述中搜集信息，自动跑示例代码，检查授权协议等等。
|
|
||||||
|
|
||||||
这个仓库的目标是：
|
|
||||||
|
|
||||||
1. 一个定义良好的**规范**。在仓库中的位置是 [spec.md](spec.md)。它是一个一直在持续优化的文档，欢迎您提 Issue 讨论其中的变化。
|
|
||||||
2. 一个**示例 README**。这个 Readme 完全遵从 Standard-readme，而且在 `example-readmes` 文件夹里有更多的示例。
|
|
||||||
3. 一个**语法提示器**用来提示在 Readme 中的语法错误。请参考 [tracking issue](https://github.com/RichardLitt/standard-readme/issues/5)。
|
|
||||||
4. 一个**生成器**用来快速搭建新的 README 的框架。请参考 [generator-standard-readme](https://github.com/RichardLitt/generator-standard-readme)。
|
|
||||||
5. 一个**标识准守规范的徽章**。请参考[徽章](#徽章)。
|
|
||||||
|
|
||||||
## 安装
|
|
||||||
|
|
||||||
这个项目使用 [node](http://nodejs.org) 和 [npm](https://npmjs.com)。请确保你本地安装了它们。
|
|
||||||
|
|
||||||
```sh
|
|
||||||
$ npm install --global standard-readme-spec
|
|
||||||
```
|
|
||||||
|
|
||||||
## 使用说明
|
|
||||||
|
|
||||||
这只是一个文档包，你可以打印出 [spec.md](spec.md) 到输出窗口。
|
|
||||||
|
|
||||||
```sh
|
|
||||||
$ standard-readme-spec
|
|
||||||
# Prints out the standard-readme spec
|
|
||||||
```
|
|
||||||
|
|
||||||
### 生成器
|
|
||||||
|
|
||||||
想要使用生成器的话，请看 [generator-standard-readme](https://github.com/RichardLitt/generator-standard-readme)。
|
|
||||||
有一个全局的可执行文件来运行包里的生成器，生成器的别名叫 `standard-readme`。
|
|
||||||
|
|
||||||
## 徽章
|
|
||||||
如果你的项目遵循 Standard-Readme 而且项目位于 Github 上，非常希望你能把这个徽章加入你的项目。它可以更多的人访问到这个项目，而且采纳 Stand-README。 加入徽章**并非强制的**。
|
|
||||||
|
|
||||||
[](https://github.com/RichardLitt/standard-readme)
|
|
||||||
|
|
||||||
为了加入徽章到 Markdown 文本里面，可以使用以下代码：
|
|
||||||
|
|
||||||
```
|
|
||||||
[](https://github.com/RichardLitt/standard-readme)
|
|
||||||
```
|
|
||||||
|
|
||||||
## 示例
|
|
||||||
|
|
||||||
想了解我们建议的规范是如何被应用的，请参考 [example-readmes](example-readmes/)。
|
|
||||||
|
|
||||||
## 相关仓库
|
|
||||||
|
|
||||||
- [Art of Readme](https://github.com/noffle/art-of-readme) — 💌 写高质量 README 的艺术。
|
|
||||||
- [open-source-template](https://github.com/davidbgk/open-source-template/) — 一个鼓励参与开源的 README 模板。
|
|
||||||
|
|
||||||
## 维护者
|
|
||||||
|
|
||||||
[@RichardLitt](https://github.com/RichardLitt)。
|
|
||||||
|
|
||||||
## 如何贡献
|
|
||||||
|
|
||||||
非常欢迎你的加入！[提一个 Issue](https://github.com/RichardLitt/standard-readme/issues/new) 或者提交一个 Pull Request。
|
|
||||||
|
|
||||||
|
|
||||||
标准 Readme 遵循 [Contributor Covenant](http://contributor-covenant.org/version/1/3/0/) 行为规范。
|
|
||||||
|
|
||||||
### 贡献者
|
|
||||||
|
|
||||||
感谢以下参与项目的人：
|
|
||||||
<a href="graphs/contributors"><img src="https://opencollective.com/standard-readme/contributors.svg?width=890&button=false" /></a>
|
|
||||||
|
|
||||||
|
|
||||||
## 使用许可
|
|
||||||
|
|
||||||
[MIT](LICENSE) © Richard Littauer
|
|
||||||
260
README.md
260
README.md
@ -1,119 +1,213 @@
|
|||||||
# Standard Readme
|
# Standard Readme
|
||||||
|
|
||||||
[](https://github.com/RichardLitt/standard-readme)
|
[](http://ipn.io)
|
||||||
|
[](http://ipfs.io/)
|
||||||
|
[](http://webchat.freenode.net/?channels=%23ipfs)
|
||||||
|
|
||||||
A standard style for README files
|
> Readme Standard Style
|
||||||
|
|
||||||
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!
|
This repo is for standardizing how READMEs should look. The goal is to have:
|
||||||
|
- A well defined specification that other people could look to;
|
||||||
|
- An example README that can be used for comparison (this README.md is the example);
|
||||||
|
- A linter that can be used to look at errors in a given Readme;
|
||||||
|
- A generator that can be used to quickly scaffold out new READMEs.
|
||||||
|
|
||||||
This repository contains:
|
** Table of Contents **
|
||||||
|
|
||||||
1. [The specification](spec.md) for how a standard README should look.
|
- [Installation](#installation)
|
||||||
2. A link to a linter you can use to keep your README maintained ([work in progress](https://github.com/RichardLitt/standard-readme/issues/5)).
|
|
||||||
3. A link to [a generator](https://github.com/RichardLitt/generator-standard-readme) you can use to create standard READMEs.
|
|
||||||
4. [A badge](#badge) to point to this spec.
|
|
||||||
5. [Examples of standard READMEs](example-readmes/) - such as this file you are reading.
|
|
||||||
|
|
||||||
Standard Readme is designed for open source libraries. Although it’s [historically](#background) made for Node and npm projects, it also applies to libraries in other languages and package managers.
|
|
||||||
|
|
||||||
|
|
||||||
## Table of Contents
|
|
||||||
|
|
||||||
- [Background](#background)
|
|
||||||
- [Install](#install)
|
|
||||||
- [Usage](#usage)
|
- [Usage](#usage)
|
||||||
- [Generator](#generator)
|
- [Specification](#specification)
|
||||||
- [Badge](#badge)
|
- [Requirements](#requirements)
|
||||||
- [Example Readmes](#example-readmes)
|
- [Sections](#sections)
|
||||||
- [Related Efforts](#related-efforts)
|
- [Title](#title)
|
||||||
- [Maintainers](#maintainers)
|
- [Banner](#banner)
|
||||||
- [Contributing](#contributing)
|
- [Badges](#badges)
|
||||||
|
- [Short Description](#short-description)
|
||||||
|
- [Long Description](#long-description)
|
||||||
|
- [Table of Contents](#table-of-contents)
|
||||||
|
- [Security](#security)
|
||||||
|
- [Background section](#background-section)
|
||||||
|
- [Installation](#installation-1)
|
||||||
|
- [Usage Section](#usage-section)
|
||||||
|
- [Extra Sections](#extra-sections)
|
||||||
|
- [API](#api)
|
||||||
|
- [Contribute](#contribute-1)
|
||||||
- [License](#license)
|
- [License](#license)
|
||||||
|
- [Contribute](#contribute)
|
||||||
|
- [License](#license-1)
|
||||||
|
|
||||||
## Background
|
## Background
|
||||||
|
|
||||||
Standard Readme started with the issue originally posed by [@maxogden](https://github.com/maxogden) over at [feross/standard](https://github.com/feross/standard) in [this issue](https://github.com/feross/standard/issues/141), about whether or not a tool to standardize readmes would be useful. A lot of that discussion ended up in [zcei's standard-readme](https://github.com/zcei/standard-readme/issues/1) repository. While working on maintaining the [IPFS](https://github.com/ipfs) repositories, I needed a way to standardize Readmes across that organization. This specification started as a result of that.
|
Standard Readme started with in the issue originally posed by [@maxogden](https://github.com/maxogden) over at [feross/standard](https://github.com/feross/standard) in [this issue](https://github.com/feross/standard/issues/141). A lot of that discussion ended up in [zcei's standard-readme](https://github.com/zcei/standard-readme/issues/1) repository. While working on maintaining the [IPFS](https://github.com/ipfs) repositories, I needed a way to standardize Readmes. This is a result of that.
|
||||||
|
|
||||||
> Your documentation is complete when someone can use your module without ever
|
### Goals:
|
||||||
having to look at its code. This is very important. This makes it possible for
|
1. A well defined **specification**. This can be found in the [Specification](#specification) section. It is a constant work in progress; please open issues to discuss changes.
|
||||||
you to separate your module's documented interface from its internal
|
2. **An example README**. This Readme is fully standard-readme compliant.
|
||||||
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.
|
|
||||||
|
|
||||||
~ [Ken Williams, Perl Hackers](http://mathforum.org/ken/perl_modules.html#document)
|
|
||||||
|
|
||||||
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:
|
|
||||||
|
|
||||||
1. A well defined **specification**. This can be found in the [Spec document](spec.md). It is a constant work in progress; please open issues to discuss changes.
|
|
||||||
2. **An example README**. This Readme is fully standard-readme compliant, and there are more examples in the `example-readmes` folder.
|
|
||||||
3. A **linter** that can be used to look at errors in a given Readme. Please refer to the [tracking issue](https://github.com/RichardLitt/standard-readme/issues/5).
|
3. A **linter** that can be used to look at errors in a given Readme. Please refer to the [tracking issue](https://github.com/RichardLitt/standard-readme/issues/5).
|
||||||
4. A **generator** that can be used to quickly scaffold out new READMEs. See [generator-standard-readme](https://github.com/RichardLitt/generator-standard-readme).
|
4. A generator that can be used to quickly scaffold out new READMEs. Please refer to the [tracking issue](https://github.com/RichardLitt/standard-readme/issues/6).
|
||||||
5. A **compliant badge** for users. See [the badge](#badge).
|
5. A compliant badge.
|
||||||
|
|
||||||
## Install
|
## Installation
|
||||||
|
|
||||||
This project uses [node](http://nodejs.org) and [npm](https://npmjs.com). Go check them out if you don't have them locally installed.
|
This project uses [node][] and [npm][]. Go check them out if you don't have them locally installed.
|
||||||
|
|
||||||
```sh
|
```sh
|
||||||
$ npm install --global standard-readme-spec
|
$ npm i -g standard-readme
|
||||||
```
|
```
|
||||||
|
|
||||||
## Usage
|
## Usage
|
||||||
|
|
||||||
This is only a documentation package. You can print out [spec.md](spec.md) to your console:
|
Currently, this is only a Readme spec.
|
||||||
|
|
||||||
```sh
|
|
||||||
$ standard-readme-spec
|
|
||||||
# Prints out the standard-readme spec
|
|
||||||
```
|
|
||||||
|
|
||||||
### Generator
|
|
||||||
|
|
||||||
To use the generator, look at [generator-standard-readme](https://github.com/RichardLitt/generator-standard-readme). There is a global executable to run the generator in that package, aliased as `standard-readme`.
|
|
||||||
|
|
||||||
## Badge
|
|
||||||
|
|
||||||
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**.
|
|
||||||
|
|
||||||
[](https://github.com/RichardLitt/standard-readme)
|
|
||||||
|
|
||||||
To add in Markdown format, use this code:
|
|
||||||
|
|
||||||
```
|
```
|
||||||
[](https://github.com/RichardLitt/standard-readme)
|
$ standard-readme
|
||||||
|
// Will output spec (this Readme)
|
||||||
```
|
```
|
||||||
|
|
||||||
## Example Readmes
|
## Specification
|
||||||
|
|
||||||
To see how the specification has been applied, see the [example-readmes](example-readmes/).
|
### Requirements
|
||||||
|
|
||||||
## Related Efforts
|
A compliant README must:
|
||||||
|
- Be called README.md (with capitalization).
|
||||||
|
- Be a valid Markdown file.
|
||||||
|
- Sections must appear in order delineated below. Optional sections may be omitted.
|
||||||
|
- Must be new lines between each section.
|
||||||
|
|
||||||
- [Art of Readme](https://github.com/noffle/art-of-readme) - 💌 Learn the art of writing quality READMEs.
|
### Sections
|
||||||
- [open-source-template](https://github.com/davidbgk/open-source-template/) - A README template to encourage open-source contributions.
|
|
||||||
|
|
||||||
## Maintainers
|
#### Title
|
||||||
|
**Status:** Required.
|
||||||
|
**Requirements:**
|
||||||
|
- Must match repository name. If it cannot, there must be a note in the long description about why.
|
||||||
|
- Must match package manager name. If it cannot, there must be a note in the long description about why.
|
||||||
|
|
||||||
[@RichardLitt](https://github.com/RichardLitt).
|
**Suggestions:**
|
||||||
|
- Should be self-evident.
|
||||||
|
|
||||||
## Contributing
|
#### Banner
|
||||||
|
**Status:** Optional.
|
||||||
|
**Requirements:**
|
||||||
|
- Must link to local image in current repository.
|
||||||
|
- Must appear directly after the title.
|
||||||
|
|
||||||
|
#### Badges
|
||||||
|
**Status:** Optional.
|
||||||
|
**Requirements:**
|
||||||
|
- Must be newline delimited.
|
||||||
|
|
||||||
|
#### Short Description
|
||||||
|
**Status:** Required.
|
||||||
|
**Requirements:**
|
||||||
|
- Must be less than 120 characters.
|
||||||
|
- Must start with `> `
|
||||||
|
- Must be on it's 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](https://github.com/RichardLitt/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 have no heading.
|
||||||
|
|
||||||
|
**Suggestions:**
|
||||||
|
- If too long, consider moving to the [Background](#background) section.
|
||||||
|
- Cover the main reasons for building the repository.
|
||||||
|
|
||||||
|
#### Table of Contents
|
||||||
|
**Status:** Required.
|
||||||
|
**Requirements:**
|
||||||
|
- Must link to all Markdown sections in the file.
|
||||||
|
- Must not have a Markdown header, `####`, but must be in bold, on it's own line.
|
||||||
|
- Must start with the next section; do not include the title.
|
||||||
|
|
||||||
|
#### Security
|
||||||
|
**Status**: Optional.
|
||||||
|
**Requirements:**
|
||||||
|
- May go here if visibility of security section is important. Otherwise, should be in [Extra Sections](#extra-sections).
|
||||||
|
|
||||||
|
#### Background section
|
||||||
|
**Status:** Optional.
|
||||||
|
**Requirements:**
|
||||||
|
- Cover motivation.
|
||||||
|
- Cover abstract dependencies.
|
||||||
|
- Cover intellecutal provenance.
|
||||||
|
|
||||||
|
#### Installation
|
||||||
|
**Status:** Required.
|
||||||
|
**Requirements:**
|
||||||
|
- Code block illustrating how to install.
|
||||||
|
|
||||||
|
Subsections:
|
||||||
|
- `Dependencies`. Required if necessary.
|
||||||
|
- `Updating`. Optional.
|
||||||
|
|
||||||
|
**Suggestions:**
|
||||||
|
- Link to prerequisite sites for language. [npmjs][], [godocs][], etc.
|
||||||
|
- Include any system-specific information needed for Installation.
|
||||||
|
- Subsection for dependencies needed for install to work.
|
||||||
|
|
||||||
|
#### Usage Section
|
||||||
|
**Status:** Required.
|
||||||
|
**Requirements:**
|
||||||
|
- Code block illustrating common usage.
|
||||||
|
- If CLI compatible, code block indicating common usage.
|
||||||
|
- 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.
|
||||||
|
|
||||||
|
#### Extra Sections
|
||||||
|
**Status**: Optional.
|
||||||
|
**Requirements:**
|
||||||
|
- None.
|
||||||
|
|
||||||
|
#### 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.
|
||||||
|
|
||||||
|
#### Contribute
|
||||||
|
**Status**: Required.
|
||||||
|
**Requirements:**
|
||||||
|
- Link to `CONTRIBUTE.md` file if there is one.
|
||||||
|
- 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:**
|
||||||
|
- Be as friendly as possible.
|
||||||
|
- Link to the GitHub issues.
|
||||||
|
|
||||||
|
#### License
|
||||||
|
**Status:** Required.
|
||||||
|
**Requirements:**
|
||||||
|
- State license initials or name.
|
||||||
|
- State license owner.
|
||||||
|
- Must be last section.
|
||||||
|
|
||||||
|
**Suggestions:**
|
||||||
|
- Link to longer License file in local repository.
|
||||||
|
|
||||||
|
## Contribute
|
||||||
|
|
||||||
Feel free to dive in! [Open an issue](https://github.com/RichardLitt/standard-readme/issues/new) or submit PRs.
|
Feel free to dive in! [Open an issue](https://github.com/RichardLitt/standard-readme/issues/new) or submit PRs.
|
||||||
|
|
||||||
Standard Readme follows the [Contributor Covenant](http://contributor-covenant.org/version/1/3/0/) Code of Conduct.
|
|
||||||
|
|
||||||
### Contributors
|
|
||||||
|
|
||||||
This project exists thanks to all the people who contribute.
|
|
||||||
<a href="graphs/contributors"><img src="https://opencollective.com/standard-readme/contributors.svg?width=890&button=false" /></a>
|
|
||||||
|
|
||||||
|
|
||||||
## License
|
## License
|
||||||
|
|
||||||
[MIT](LICENSE) © Richard Littauer
|
MIT (c) Protocol Labs
|
||||||
|
|
||||||
|
[node]: http://nodejs.org
|
||||||
|
[npm]: https://npmjs.com
|
||||||
@ -1,68 +0,0 @@
|
|||||||
# Title
|
|
||||||
|
|
||||||
![banner]()
|
|
||||||
|
|
||||||
![badge]()
|
|
||||||
![badge]()
|
|
||||||
[](LICENSE)
|
|
||||||
[](https://github.com/RichardLitt/standard-readme)
|
|
||||||
|
|
||||||
This is an example file with maximal choices selected.
|
|
||||||
|
|
||||||
This is a long description.
|
|
||||||
|
|
||||||
## Table of Contents
|
|
||||||
|
|
||||||
- [Security](#security)
|
|
||||||
- [Background](#background)
|
|
||||||
- [Install](#install)
|
|
||||||
- [Usage](#usage)
|
|
||||||
- [API](#api)
|
|
||||||
- [Contributing](#contributing)
|
|
||||||
- [License](#license)
|
|
||||||
|
|
||||||
## Security
|
|
||||||
|
|
||||||
### Any optional sections
|
|
||||||
|
|
||||||
## Background
|
|
||||||
|
|
||||||
### Any optional sections
|
|
||||||
|
|
||||||
## Install
|
|
||||||
|
|
||||||
This module depends upon a knowledge of [Markdown]().
|
|
||||||
|
|
||||||
```
|
|
||||||
```
|
|
||||||
|
|
||||||
### Any optional sections
|
|
||||||
|
|
||||||
## Usage
|
|
||||||
|
|
||||||
```
|
|
||||||
```
|
|
||||||
|
|
||||||
Note: The `license` badge image link at the top of this file should be updated with the correct `:user` and `:repo`.
|
|
||||||
|
|
||||||
### Any optional sections
|
|
||||||
|
|
||||||
## API
|
|
||||||
|
|
||||||
### Any optional sections
|
|
||||||
|
|
||||||
## More optional sections
|
|
||||||
|
|
||||||
## Contributing
|
|
||||||
|
|
||||||
See [the contributing file](CONTRIBUTING.md)!
|
|
||||||
|
|
||||||
PRs accepted.
|
|
||||||
|
|
||||||
Small note: If editing the Readme, please conform to the [standard-readme](https://github.com/RichardLitt/standard-readme) specification.
|
|
||||||
|
|
||||||
### Any optional sections
|
|
||||||
|
|
||||||
## License
|
|
||||||
|
|
||||||
[MIT © Richard McRichface.](../LICENSE)
|
|
||||||
@ -1,21 +0,0 @@
|
|||||||
# Title
|
|
||||||
|
|
||||||
This is an example file with default selections.
|
|
||||||
|
|
||||||
## Install
|
|
||||||
|
|
||||||
```
|
|
||||||
```
|
|
||||||
|
|
||||||
## Usage
|
|
||||||
|
|
||||||
```
|
|
||||||
```
|
|
||||||
|
|
||||||
## Contributing
|
|
||||||
|
|
||||||
PRs accepted.
|
|
||||||
|
|
||||||
## License
|
|
||||||
|
|
||||||
MIT © Richard McRichface
|
|
||||||
23
index.js
Normal file
23
index.js
Normal file
@ -0,0 +1,23 @@
|
|||||||
|
var mdast = require('mdast')
|
||||||
|
var lint = require('mdast-lint')
|
||||||
|
var fs = require('graceful-fs')
|
||||||
|
var remarkTitle = require('remark-title')
|
||||||
|
var doc = './README.md'
|
||||||
|
// TODO Replace README with readme option
|
||||||
|
|
||||||
|
fs.writeFileSync(doc, mdast().use(remarkTitle, {
|
||||||
|
title: 'IPFS Readme Standard'
|
||||||
|
}, lint).process(
|
||||||
|
fs.readFileSync(doc, 'utf8'), function (err, file, res) {
|
||||||
|
if (err) {
|
||||||
|
console.log(err)
|
||||||
|
return
|
||||||
|
}
|
||||||
|
|
||||||
|
if (file.messages[0] != null) {
|
||||||
|
console.log(file.messages)
|
||||||
|
} else {
|
||||||
|
console.log('No errors found!')
|
||||||
|
}
|
||||||
|
})
|
||||||
|
)
|
||||||
5
package-lock.json
generated
5
package-lock.json
generated
@ -1,5 +0,0 @@
|
|||||||
{
|
|
||||||
"name": "standard-readme-spec",
|
|
||||||
"version": "1.2.0",
|
|
||||||
"lockfileVersion": 1
|
|
||||||
}
|
|
||||||
51
package.json
51
package.json
@ -1,45 +1,40 @@
|
|||||||
{
|
{
|
||||||
"name": "standard-readme-spec",
|
"name": "standard-readme",
|
||||||
"version": "1.2.0",
|
"version": "1.0.2",
|
||||||
"description": "A standard style for README files",
|
"description": "Readme Standard Style",
|
||||||
"bin": "cat.sh",
|
"main": "index.js",
|
||||||
|
"scripts": {
|
||||||
|
"test": "echo \"Error: no test specified\" && exit 1",
|
||||||
|
"build": "babel src -d lib"
|
||||||
|
},
|
||||||
"repository": {
|
"repository": {
|
||||||
"type": "git",
|
"type": "git",
|
||||||
"url": "git+https://github.com/RichardLitt/standard-readme.git"
|
"url": "git+https://github.com/ipfs/ipfs-readme-standard.git"
|
||||||
},
|
},
|
||||||
"keywords": [
|
"keywords": [
|
||||||
"standard",
|
|
||||||
"markdown",
|
"markdown",
|
||||||
"readme",
|
"readme",
|
||||||
"parse",
|
"parse",
|
||||||
"lint",
|
"lint",
|
||||||
"standard-readme",
|
"standard"
|
||||||
"spec",
|
|
||||||
"md",
|
|
||||||
"documentation"
|
|
||||||
],
|
],
|
||||||
"author": {
|
"author": "Richard Littauer <richard.littauer@gmail.com> (http://burntfen.com)",
|
||||||
"name": "Richard Littauer",
|
|
||||||
"email": "richard.littauer@gmail.com",
|
|
||||||
"url": "http://burntfen.com"
|
|
||||||
},
|
|
||||||
"license": "MIT",
|
"license": "MIT",
|
||||||
"bugs": {
|
"bugs": {
|
||||||
"url": "https://github.com/RichardLitt/standard-readme/issues"
|
"url": "https://github.com/ipfs/ipfs-readme-standard/issues"
|
||||||
},
|
},
|
||||||
"homepage": "https://github.com/RichardLitt/standard-readme",
|
"homepage": "https://github.com/ipfs/ipfs-readme-standard#readme",
|
||||||
"dependencies": {
|
"dependencies": {
|
||||||
"opencollective": "^1.0.3"
|
"graceful-fs": "^4.1.2",
|
||||||
|
"mdast": "^2.1.0",
|
||||||
|
"mdast-lint": "^1.1.1",
|
||||||
|
"remark-title": "^1.0.0"
|
||||||
|
},
|
||||||
|
"devDependencies": {
|
||||||
|
"babel-cli": "^6.3.17"
|
||||||
},
|
},
|
||||||
"coordinates": [
|
"coordinates": [
|
||||||
52.5173031,
|
42.3811742,
|
||||||
13.4535065
|
-71.0972239
|
||||||
],
|
]
|
||||||
"collective": {
|
|
||||||
"type": "opencollective",
|
|
||||||
"url": "https://opencollective.com/standard-readme"
|
|
||||||
},
|
|
||||||
"scripts": {
|
|
||||||
"postinstall": "opencollective-postinstall"
|
|
||||||
}
|
|
||||||
}
|
}
|
||||||
|
|||||||
240
spec.md
240
spec.md
@ -1,240 +0,0 @@
|
|||||||
# Specification
|
|
||||||
|
|
||||||
A compliant README must satisfy all the requirements listed below.
|
|
||||||
|
|
||||||
> Note: Standard Readme is designed for open source libraries. Although it's [historically](README.md#background) made for Node and npm projects, it also applies to libraries in other languages and package managers.
|
|
||||||
|
|
||||||
**Requirements:**
|
|
||||||
- Be called README.md (with capitalization).
|
|
||||||
- If the project supports i18n, the file must be named accordingly: `README.de.md`, where `de` is the BCP 47 Language tag. For naming, prioritize non-regional subtags for languages. If there is only one README and the language is not English, then a different language in the text is permissible without needing to to specify the BCP tag: e.g., `README.md` can be in German if there is no `README.md` in another language. Where there are multiple languages, `README.md` is reserved for English.
|
|
||||||
- Be a valid Markdown file.
|
|
||||||
- Sections must appear in order given below. Optional sections may be omitted.
|
|
||||||
- Sections must have the titles listed below, unless otherwise specified. If the README is in another language, the titles must be translated into that language.
|
|
||||||
- Must not contain broken links.
|
|
||||||
- If there are code examples, they should be linted in the same way as the code is linted in the rest of the project.
|
|
||||||
|
|
||||||
## Table of Contents
|
|
||||||
|
|
||||||
_Note: This is only a navigation guide for the specification, and does not define or mandate terms for any specification-compliant documents._
|
|
||||||
|
|
||||||
- [Sections](#sections)
|
|
||||||
- [Title](#title)
|
|
||||||
- [Banner](#banner)
|
|
||||||
- [Badges](#badges)
|
|
||||||
- [Short Description](#short-description)
|
|
||||||
- [Long Description](#long-description)
|
|
||||||
- [Table of Contents](#table-of-contents-1)
|
|
||||||
- [Security](#security)
|
|
||||||
- [Background](#background)
|
|
||||||
- [Install](#install)
|
|
||||||
- [Usage](#usage)
|
|
||||||
- [Extra Sections](#extra-sections)
|
|
||||||
- [API](#api)
|
|
||||||
- [Maintainers](#maintainers)
|
|
||||||
- [Thanks](#thanks)
|
|
||||||
- [Contributing](#contributing)
|
|
||||||
- [License](#license)
|
|
||||||
- [Definitions](#definitions)
|
|
||||||
|
|
||||||
## Sections
|
|
||||||
|
|
||||||
### Title
|
|
||||||
**Status:** Required.
|
|
||||||
|
|
||||||
**Requirements:**
|
|
||||||
- Title must match repository, folder and package manager names - or it may have another, relevant title with the repository, folder, and package manager title next to it in italics and in parentheses. For instance:
|
|
||||||
|
|
||||||
```markdown
|
|
||||||
# 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](#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](https://github.com/RichardLitt/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](https://github.com/RichardLitt/gh-description) to set and get GitHub description.
|
|
||||||
- Use `npm show . description` to show the description from a local [npm](https://npmjs.com) 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](#title).
|
|
||||||
|
|
||||||
**Suggestions:**
|
|
||||||
- If too long, consider moving to the [Background](#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."
|
|
||||||
|
|
||||||
~ [Kirrily "Skud" Robert, perlmodstyle](http://perldoc.perl.org/perlmodstyle.html)
|
|
||||||
|
|
||||||
### Table of Contents
|
|
||||||
**Status:** Required; optional for READMEs shorter than 100 lines.
|
|
||||||
|
|
||||||
**Requirements:**
|
|
||||||
- Must link to all Markdown sections in the file.
|
|
||||||
- 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](#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](#definitions).
|
|
||||||
|
|
||||||
**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](https://npmjs.com), [godocs](https://godoc.org), 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.
|
|
||||||
|
|
||||||
### Usage
|
|
||||||
**Status:** Required by default, optional for [documentation repositories](#definitions).
|
|
||||||
|
|
||||||
**Requirements:**
|
|
||||||
- Code block illustrating common usage.
|
|
||||||
- If CLI compatible, code block indicating common usage.
|
|
||||||
- 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.
|
|
||||||
- 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 have titles.
|
|
||||||
- This should contain any other sections that are relevant, placed after [Usage](#usage) and before [API](#api).
|
|
||||||
- Specifically, the [Security](#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.
|
|
||||||
|
|
||||||
### Maintainer(s)
|
|
||||||
**Status**: Optional.
|
|
||||||
|
|
||||||
**Requirements:**
|
|
||||||
- Must be called `Maintainer` or `Maintainers`.
|
|
||||||
- List maintainer(s) for a repository, along with one way of contacting them (e.g. GitHub link or email).
|
|
||||||
|
|
||||||
**Suggestions:**
|
|
||||||
- This should be a small list of people in charge of the repo. This should not be everyone with access rights, such as an entire organization, but the people who should be pinged and who are in charge of the direction and maintenance of the repository.
|
|
||||||
- Listing past maintainers is good for attribution, and kind.
|
|
||||||
|
|
||||||
### 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](https://spdx.org/licenses/) 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](https://docs.npmjs.com/files/package.json#license)).
|
|
||||||
- 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](https://github.com/RichardLitt/knowledge).
|
|
||||||
Loading…
Reference in New Issue
Block a user