Move spec to spec, rename Installation to install
This commit is contained in:
Richard Littauer
parent
288e7e520c
commit
2986c49901
200
README.md
200
README.md
@ -7,34 +7,19 @@
|
|||||||
|
|
||||||
> Readme Standard Style
|
> Readme Standard Style
|
||||||
|
|
||||||
This repo is for standardizing how READMEs should look. The goal is to have a spec, a linter, a generator, a badge, and examples.
|
This repo is for standardizing how READMEs should look. The goal is to have a spec, a linter, a generator, a badge, and examples. This document is also an example of a standard README.
|
||||||
|
|
||||||
## Table of Contents
|
## Table of Contents
|
||||||
|
|
||||||
- [Background](#background)
|
- [Background](#background)
|
||||||
- [Goals:](#goals)
|
- [Goals](#goals)
|
||||||
- [Installation](#installation)
|
- [Installation](#installation)
|
||||||
- [Usage](#usage)
|
- [Usage](#usage)
|
||||||
|
- [Generator](#generator)
|
||||||
- [Badge](#badge)
|
- [Badge](#badge)
|
||||||
- [Specification](#specification)
|
- [Example Readmes](#example-readmes)
|
||||||
- [Requirements](#requirements)
|
- [Contribute](#contribute)
|
||||||
- [Sections](#sections)
|
- [License](#license)
|
||||||
- [Title](#title)
|
|
||||||
- [Banner](#banner)
|
|
||||||
- [Badges](#badges)
|
|
||||||
- [Short Description](#short-description)
|
|
||||||
- [Long Description](#long-description)
|
|
||||||
- [Table of Contents](#table-of-contents-1)
|
|
||||||
- [Security](#security)
|
|
||||||
- [Background Section](#background-section)
|
|
||||||
- [Installation](#installation-1)
|
|
||||||
- [Usage Section](#usage-section)
|
|
||||||
- [Extra Sections](#extra-sections)
|
|
||||||
- [API](#api)
|
|
||||||
- [Contribute](#contribute)
|
|
||||||
- [License](#license)
|
|
||||||
- [Contribute](#contribute-1)
|
|
||||||
- [License](#license-1)
|
|
||||||
|
|
||||||
## Background
|
## Background
|
||||||
|
|
||||||
@ -50,16 +35,16 @@ change the module's internals as long as the interface remains the same.
|
|||||||
|
|
||||||
~ [Ken Williams, Perl Hackers](http://mathforum.org/ken/perl_modules.html#document)
|
~ [Ken Williams, Perl Hackers](http://mathforum.org/ken/perl_modules.html#document)
|
||||||
|
|
||||||
### Goals:
|
### Goals
|
||||||
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.
|
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.
|
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. See [generator-standard-readme](https://github.com/RichardLitt/generator-standard-readme).
|
||||||
5. A **compliant badge** for users. See [the badge](#badge).
|
5. A **compliant badge** for users. See [the badge](#badge).
|
||||||
|
|
||||||
## Installation
|
## Install
|
||||||
|
|
||||||
This project uses [node][] and [npm][]. Go check them out if you don't have them locally installed.
|
This project uses [node](http://nodejs.org) and [npm](https://npmjs.com). Go check them out if you don't have them locally installed.
|
||||||
|
|
||||||
```sh
|
```sh
|
||||||
$ npm i -g standard-readme
|
$ npm i -g standard-readme
|
||||||
@ -67,11 +52,11 @@ $ npm i -g standard-readme
|
|||||||
|
|
||||||
## Usage
|
## Usage
|
||||||
|
|
||||||
Currently, this is only a Readme spec.
|
Currently, this is only a README spec.
|
||||||
|
|
||||||
```
|
```
|
||||||
$ standard-readme
|
$ standard-readme
|
||||||
// Will output spec (this Readme)
|
// Will print spec.md to the console
|
||||||
```
|
```
|
||||||
|
|
||||||
### Generator
|
### Generator
|
||||||
@ -94,164 +79,6 @@ To add in Markdown format, use this code:
|
|||||||
|
|
||||||
To see how the specification has been applied, see the [example-readmes](example-readmes/).
|
To see how the specification has been applied, see the [example-readmes](example-readmes/).
|
||||||
|
|
||||||
## Specification
|
|
||||||
|
|
||||||
### Requirements
|
|
||||||
|
|
||||||
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.
|
|
||||||
|
|
||||||
**Suggestions:**
|
|
||||||
- A "Back to Top" link for longer sections can be useful, but is not required by any means.
|
|
||||||
|
|
||||||
### Sections
|
|
||||||
|
|
||||||
#### 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.
|
|
||||||
|
|
||||||
**Suggestions:**
|
|
||||||
- Should be self-evident.
|
|
||||||
|
|
||||||
#### 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.
|
|
||||||
- "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.
|
|
||||||
**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 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: A `See Also` section is also fitting.
|
|
||||||
|
|
||||||
#### 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.
|
|
||||||
- If relevant, point to a runnable file for the usage code.
|
|
||||||
|
|
||||||
**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.
|
|
||||||
- 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.
|
|
||||||
|
|
||||||
#### Contribute
|
|
||||||
**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 `CONTRIBUTE.md` file -- if there is one.
|
|
||||||
- Be as friendly as possible.
|
|
||||||
- Link to the GitHub issues.
|
|
||||||
- Link to Code of Conduct. This is often in Contribute, or organization wide, so may not be necessary for each module.
|
|
||||||
|
|
||||||
#### 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
|
## 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.
|
||||||
@ -261,6 +88,3 @@ Standard Readme follows the [Contributor Covenant](http://contributor-covenant.o
|
|||||||
## License
|
## License
|
||||||
|
|
||||||
MIT (c) Protocol Labs
|
MIT (c) Protocol Labs
|
||||||
|
|
||||||
[node]: http://nodejs.org
|
|
||||||
[npm]: https://npmjs.com
|
|
||||||
2
index.js
2
index.js
@ -1,5 +1,5 @@
|
|||||||
var fs = require('graceful-fs')
|
var fs = require('graceful-fs')
|
||||||
var doc = 'README.md'
|
var doc = 'spec.md'
|
||||||
|
|
||||||
fs.readFile(doc, { encoding: 'utf8' }, function(err, data) {
|
fs.readFile(doc, { encoding: 'utf8' }, function(err, data) {
|
||||||
console.log(data)
|
console.log(data)
|
||||||
|
|||||||
157
spec.md
Normal file
157
spec.md
Normal file
@ -0,0 +1,157 @@
|
|||||||
|
## Specification
|
||||||
|
|
||||||
|
### Requirements
|
||||||
|
|
||||||
|
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.
|
||||||
|
|
||||||
|
**Suggestions:**
|
||||||
|
- A "Back to Top" link for longer sections can be useful, but is not required by any means.
|
||||||
|
|
||||||
|
### Sections
|
||||||
|
|
||||||
|
#### 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.
|
||||||
|
|
||||||
|
**Suggestions:**
|
||||||
|
- Should be self-evident.
|
||||||
|
|
||||||
|
#### 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](https://npmjs.com) 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.
|
||||||
|
- "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.
|
||||||
|
**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 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: A `See Also` section is also fitting.
|
||||||
|
|
||||||
|
#### Install
|
||||||
|
**Status:** Required.
|
||||||
|
**Requirements:**
|
||||||
|
- Code block illustrating how to install.
|
||||||
|
|
||||||
|
Subsections:
|
||||||
|
- `Dependencies`. Required if necessary.
|
||||||
|
- `Updating`. Optional.
|
||||||
|
|
||||||
|
**Suggestions:**
|
||||||
|
- Link to prerequisite sites for language. [npmjs](https://npmjs.com), [godocs](https://godoc.org), 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.
|
||||||
|
- If relevant, point to a runnable file for the usage code.
|
||||||
|
|
||||||
|
**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.
|
||||||
|
- 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.
|
||||||
|
|
||||||
|
#### Contribute
|
||||||
|
**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 `CONTRIBUTE.md` file -- if there is one.
|
||||||
|
- Be as friendly as possible.
|
||||||
|
- Link to the GitHub issues.
|
||||||
|
- Link to Code of Conduct. This is often in Contribute, or organization wide, so may not be necessary for each module.
|
||||||
|
|
||||||
|
#### 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.
|
||||||
Loading…
Reference in New Issue
Block a user