Skip to content

Commit db28f49

Browse files
billiegoosebilliegoose
committed
Update README
1 parent 133c824 commit db28f49

File tree

1 file changed

+87
-109
lines changed

1 file changed

+87
-109
lines changed

‎README.md

+87-109
Original file line numberDiff line numberDiff line change
@@ -8,157 +8,135 @@ Quickly generate or update your project's README.md
88

99
<!-- /BADGES -->
1010

11-
12-
## To test it out
13-
14-
```sh
15-
git clone https://github.com/update-doc/update-doc-license
16-
cd update-doc-license
17-
npm install
18-
npm link
19-
cd ..
20-
git clone https://github.com/update-doc/update-doc
21-
cd update-doc
22-
npm install
23-
npm link update-doc-license
24-
npm run watchify &
25-
node update-doc-cli.js -p license README.md
26-
```
27-
28-
Try changing the value of 'license' in the package.json file and rerunning it.
29-
3011
## Installation
3112

3213
```
3314
npm install update-readme --save
3415
```
3516

36-
## Usage concept
37-
38-
It uses a browserify-like syntax for plugins. Something like...
39-
40-
```json
41-
"scripts": {
42-
"readme": "update-readme -p title -p license README.md",
43-
"license": "update-readme -p full-license LICENSE.md",
44-
"history": "update-readme -p git-history-file HISTORY.md",
45-
"update": "npm run readme; npm run license; npm run history"
46-
}
47-
```
48-
49-
We can literally use the browserify arg parser. Because @substack is awesome like that.
50-
5117
## CLI usage
5218

5319
The command line API is intentionally similar to that of browserify or babel.
20+
Here's an example command demonstrating the plugins currently available:
5421

5522
```sh
56-
update-doc -p name-and-description -p [ license --plugin-option=foobar --use-things ] README.md
23+
update-readme -p name-and-description -p [ license --long ] -p installation
5724
```
5825

5926
## JavaScript API
6027

61-
The JS API is intentionally similar to that of browserify or babel.
28+
The JS API is still in flux but I would like it to be similar to babel or browserify.
29+
It is designed to be more explicit in order to be more flexible for developers.
30+
For instance, whereas the CLI prepends `'update-readme-'` to the plugin names,
31+
`'module'` can be any valid string to pass to `require()` including local files
32+
that are project specific.
6233

63-
```js
64-
const updateDoc = require('update-doc')
65-
let command = updateDoc({
34+
```
35+
require('update-readme')({
36+
readme: 'README.md',
6637
plugins: [
67-
'update-doc-name-and-description',
68-
['update-doc-license', {'plugin-option': 'foobar', 'use-things': true}]
38+
{
39+
module: 'update-readme-name-and-description',
40+
options: {}
41+
}, {
42+
module: 'update-readme-license',
43+
options: { long: true }
44+
}
6945
]
7046
})
71-
command('README.md').then(() => {
72-
console.log('README.md has been updated.')
73-
})
47+
.then( ... )
48+
.catch( ... )
7449
```
7550

76-
## Plugin Authoring for 0.0.x
51+
## Plugin Authoring API
52+
53+
Plugins can be thought of as filters. The README file gets split into
54+
sections by headers (using a regex and assuming headers start with a `#`).
55+
Those sections are passed as an array of Markdown strings to the plugin, which
56+
can then loop through all the sections. Global plugins (for linting, etc) can
57+
operate on every section. However most plugins will compare each section to a
58+
regex and only update the specific section its concerned with. Plugins can also
59+
loop through the sections and see that their section is missing and insert a new
60+
section into the README.
7761

78-
Plugins can be either global or for a particular section.
79-
Sections are identified by their title. So for instance, a plugin that
80-
generates the license section of a README might look like this:
62+
### API
8163

82-
```js
83-
// basic license plugin
84-
const path = require('path')
64+
Plugins should export a single function call with the following type signature:
65+
66+
```
8567
/**
86-
* @param {Section} section - Represents a section of the Markdown document (see details below)
87-
* @param {object} pluginOptions - Options passed to only your plugin
88-
* @param {object} globalOptions - Options passed to every plugin
89-
* @return {Promise} - Asynchronous plugins must return a promise that resolves when the plugin is done. (Synchronous plugins do not need to return anything.)
68+
* An update-readme plugin
69+
* @param {string[]} sections - the sections of the README file
70+
* @param {object} pluginOptions - any commandline options passed to the plugin
71+
* @param {object} globalOptions - reserved for global options
72+
*
73+
* @return {string[] | Promise(string[])} - the processed Markdown sections
9074
*/
91-
module.exports = function (section, pluginOptions, globalOptions) {
92-
let pkg = require(path.join(process.cwd(), 'package.json'))
93-
94-
section.body = [
95-
'',
96-
'Copyright ' + pkg.author,
97-
'License: ' pkg.license
98-
]
9975
}
100-
/** Register this module to operate on sections that have this title.
101-
* (titles are lowercased and trimmed before comparison)
102-
* If no title is provided, that means the plugin is global and will
103-
* be handed the root section.
104-
*/
105-
module.exports.title = 'License'
10676
```
10777

108-
### Sections
109-
`update-doc` works by parsing a Markdown file into sections. Each section
110-
has a `title` that is a single line of text and a `body` that is an array of lines of text.
111-
Sections also have a `level` which indicates the number of `#` at the front of the title.
112-
E.g. `## Getting Started` is a level 2 header, `### foo` is a level 3 header, and
113-
so on. Right now the level information isn't used for anything.
78+
### Example Plugin
11479

115-
Here's an example of how `update-doc` would parse this Markdown:
80+
This is an example of a plugin that just updates the copyright year in the License section.
11681

117-
# my-module
118-
This is the best module ever.
82+
```
83+
export default function CopyrightYear (sections, { year }) {
84+
year = year || (new Date()).getFullYear()
85+
for (let n in sections) {
86+
if (sections[n].match(/^#+\s*License/i)) {
87+
sections[n] = sections[n].replace(/Copyright \d\d\d\d/g, `Copyright ${year}`)
88+
}
89+
}
90+
return sections
91+
}
92+
```
11993

120-
## Installation
94+
Example usage:
12195

122-
Pay careful attention...
96+
update-readme -p copyrightyear
12397

98+
Since the year is an option we can even override it
12499

125-
is represented by a section looking like this:
100+
update-readme -p [ copyrightyear --year 1997 ]
126101

127-
```js
128-
{
129-
parent: null,
130-
level: 1,
131-
title: ' my-module',
132-
body: [
133-
'This is the best module ever.',
134-
''
135-
],
136-
subsections: [
137-
{
138-
parent: null,
139-
level: 2,
140-
title: ' Installation',
141-
body: [
142-
'',
143-
'Pay careful attention...'
144-
]
145-
subsections: [],
146-
}
147-
]
148-
}
149-
```
150-
151-
### Naming
102+
### Plugin Naming Convention
152103

153104
Plugins can be named whatever you want, however if you publish the plugin
154-
the name needs to start with `update-doc-` or it won't work with the command line
155-
`update-doc` tool, which prepends `update-doc-` to the name of plugins to know
105+
the name needs to start with `update-readme-` or it won't work with the command line
106+
`update-readme` tool, which prepends `update-readme-` to the name of plugins to know
156107
what module to use.
157108

158109
You can write a plugin specific to your project though, and use it via the
159110
JavaScript API, since plugin names have to be fully spelled out there.
160111

112+
## Testing the latest version
113+
114+
```sh
115+
git clone https://github.com/update-readme/update-readme-license
116+
cd update-readme-license
117+
npm install
118+
npm link
119+
cd ..
120+
git clone https://github.com/update-readme/update-readme
121+
cd update-readme
122+
npm install
123+
npm link update-readme-license
124+
npm run build
125+
node dist/bin/update-readme.js -p [ license --long ]
126+
```
127+
128+
Try changing the value of 'license' in the package.json file and rerunning it.
129+
161130
## License
162131

163132
Copyright 2017 William Hilton.
164-
Licensed under [The Unlicense](http://unlicense.org/).
133+
This is free and unencumbered software released into the public domain.
134+
135+
Anyone is free to copy, modify, publish, use, compile, sell, or distribute this software, either in source code form or as a compiled binary, for any purpose, commercial or non-commercial, and by any means.
136+
137+
In jurisdictions that recognize copyright laws, the author or authors of this software dedicate any and all copyright interest in the software to the public domain. We make this dedication for the benefit of the public at large and to the detriment of our heirs and
138+
successors. We intend this dedication to be an overt act of relinquishment in perpetuity of all present and future rights to this software under copyright law.
139+
140+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 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 SOFTWARE.
141+
142+
For more information, please refer to <http://unlicense.org/>

0 commit comments

Comments
 (0)