Skip to content

Commit eeaeb59

Browse files
2fd2fd
committed
create README.md dynamically
1 parent d5ce7a6 commit eeaeb59

File tree

4 files changed

+269
-130
lines changed

4 files changed

+269
-130
lines changed

‎README.handlebars‎

Lines changed: 200 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,200 @@
1+
# {{project.description}}
2+
3+
[![Build Status](https://travis-ci.org/2fd/graphdoc.svg?branch=master)](https://travis-ci.org/2fd/graphdoc)
4+
![npm (scoped)](https://img.shields.io/npm/v/@2fd/graphdoc.svg?style=flat-square)
5+
![GitHub tag](https://img.shields.io/github/tag/2fd/graphdoc.svg?style=flat-square)
6+
7+
* [demos](#demos)
8+
* [install](#install)
9+
* [use](#use)
10+
* [plugin](#plugin)
11+
* [template](#template)
12+
* [contributors](#contributors)
13+
14+
## Demos
15+
16+
* Facebook Test [Star Wars](https://2fd.github.io/graphdoc/star-wars)
17+
* [Github V4 API](https://2fd.github.io/graphdoc/github)
18+
* [Shopify API](https://2fd.github.io/graphdoc/shopify/)
19+
* [Pokemon GraphQL](https://2fd.github.io/graphdoc/pokemon)
20+
21+
## Install
22+
23+
```bash
24+
npm install -g @2fd/graphdoc
25+
```
26+
27+
## Use
28+
29+
### Generate documentation from live endpoint
30+
31+
```bash
32+
> graphdoc -e http://localhost:8080/graphql -o ./doc/schema
33+
```
34+
35+
### Generate documentation from IDL file
36+
37+
```bash
38+
> graphdoc -s ./schema.graphql -o ./doc/schema
39+
```
40+
41+
### Generate documentation from for the ["modularized schema"](http://dev.apollodata.com/tools/graphql-tools/generate-schema.html#modularizing) of graphql-tools
42+
43+
```bash
44+
> graphdoc -s ./schema.js -o ./doc/schema
45+
```
46+
47+
> [`./schema.graphql`](https://github.com/2fd/graphdoc/blob/master/test/starwars.graphql) must be able to be interpreted with [graphql-js/utilities#buildSchema](http://graphql.org/graphql-js/utilities/#buildschema)
48+
49+
50+
### Generate documentation from json file
51+
52+
```bash
53+
> graphdoc -s ./schema.json -o ./doc/schema
54+
```
55+
56+
> `./schema.json` contains the result of [GraphQL introspection query](https://github.com/2fd/graphdoc/blob/gh-pages/introspection.graphql)
57+
58+
### Puts the options in your `package.json`
59+
60+
```javascript
61+
// package.json
62+
63+
{
64+
"name": "project",
65+
// [...]
66+
"graphdoc": {
67+
"endpoint": "http://localhost:8080/graphql",
68+
"output": "./doc/schema",
69+
}
70+
}
71+
```
72+
73+
And execute
74+
75+
```bash
76+
> graphdoc
77+
```
78+
79+
### Help
80+
81+
```bash
82+
83+
> graphdoc -h
84+
{{{bash "node ./bin/graphdoc.js --help"}}}
85+
```
86+
87+
## Plugin
88+
89+
In graphdoc a plugin is simply an object that controls the content that is displayed
90+
on every page of your document.
91+
92+
This object should only implement the [`PluginInterface`](https://github.com/2fd/graphdoc/blob/master/lib/interface.d.ts#L12-L117).
93+
94+
### Make a Plugin
95+
96+
To create your own plugin you should only create it as a `plain object`
97+
or a `constructor` and export it as `default`
98+
99+
If you export your plugin as a constructor, when going to be initialized,
100+
will receive three parameters
101+
102+
* `schema`: The full the result of [GraphQL instrospection query](https://github.com/2fd/graphdoc/blob/gh-pages/introspection.graphql)
103+
* `projectPackage`: The content of `package.json` of current project (or the content of file defined with `--config` flag).
104+
* `graphdocPackag`: The content of `package.json` of graphdoc.
105+
106+
> For performance reasons all plugins receive the reference to the same object
107+
> and therefore should not modify them directly as it could affect the behavior
108+
> of other plugins (unless of course that is your intention)
109+
110+
#### Examples
111+
112+
```typescript
113+
114+
// es2015 export constructor
115+
export default class MyPlugin {
116+
constructor(schema, projectPackage, graphdocPackag){}
117+
getAssets() { /* ... */ }
118+
/* ... */
119+
}
120+
121+
```
122+
123+
```typescript
124+
// es2015 export plain object
125+
export default cost myPlugin = {
126+
getAssets() { /* ... */ },
127+
/* ... */
128+
}
129+
```
130+
131+
```javascript
132+
133+
// export constructor
134+
function MyPlugin(schema, projectPackage, graphdocPackage) { /* ... */ }
135+
136+
MyPlugin.prototype.getAssets = function() { /* ... */ };
137+
/* ... */
138+
139+
exports.default = MyPlugin;
140+
```
141+
142+
```javascript
143+
144+
// export plain object
145+
146+
exports.default = {
147+
getAssets: function() { /* ... */ },
148+
/* ... */
149+
}
150+
151+
```
152+
153+
### Use plugin
154+
155+
You can use the plugins in 2 ways.
156+
157+
158+
#### Use plugins with command line
159+
160+
```bash
161+
> graphdoc -p graphdoc/plugins/default \
162+
-p some-dependencie/plugin \
163+
-p ./lib/plugin/my-own-plugin \
164+
-s ./schema.json -o ./doc/schema
165+
```
166+
167+
#### Use plugins with `package.json`
168+
169+
```javascript
170+
// package.json
171+
172+
{
173+
"name": "project",
174+
// [...]
175+
"graphdoc": {
176+
"endpoint": "http://localhost:8080/graphql",
177+
"output": "./doc/schema",
178+
"plugins": [
179+
"graphdoc/plugins/default",
180+
"some-dependencie/plugin",
181+
"./lib/plugin/my-own-plugin"
182+
]
183+
}
184+
}
185+
```
186+
187+
### Build-in plugin
188+
189+
> TODO
190+
191+
## Template
192+
193+
> TODO
194+
195+
196+
## Contributors
197+
198+
{{#each contributors}}
199+
- [<img src="{{{avatar_url}}}" width="40"> {{{login}}}]({{{html_url}}})
200+
{{/each}}

‎README.md‎

Lines changed: 37 additions & 130 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,13 @@
44
![npm (scoped)](https://img.shields.io/npm/v/@2fd/graphdoc.svg?style=flat-square)
55
![GitHub tag](https://img.shields.io/github/tag/2fd/graphdoc.svg?style=flat-square)
66

7+
* (demos)[#demos]
8+
* (install)[#install]
9+
* (use)[#use]
10+
* (plugin)[#plugin]
11+
* (template)[#template]
12+
* (contributors)[#contributors]
13+
714
## Demos
815

916
* Facebook Test [Star Wars](https://2fd.github.io/graphdoc/star-wars)
@@ -73,25 +80,28 @@ And execute
7380
```bash
7481

7582
> graphdoc -h
76-
77-
Static page generator for documenting GraphQL Schema v1.2.0
78-
79-
Usage: graphdoc [OPTIONS]
80-
81-
[OPTIONS]:
82-
-c, --config Configuration file [./package.json].
83-
-e, --endpoint Graphql http endpoint ["https://domain.com/graphql"].
84-
-x, --header HTTP header for request (use with --endpoint). ["Authorization: Token cb8795e7"].
85-
-q, --query HTTP querystring for request (use with --endpoint) ["token=cb8795e7"].
86-
-s, --schema Graphql Schema file ["./schema.json"].
87-
-p, --plugin Use plugins [default=graphdoc/plugins/default].
88-
-t, --template Use template [default=graphdoc/template/slds].
89-
-o, --output Output directory.
90-
-b, --base-url Base url for templates.
91-
-f, --force Delete outputDirectory if exists.
92-
-v, --verbose Output more information.
93-
-V, --version Show graphdoc version.
94-
-h, --help Print this help
83+
84+
Static page generator for documenting GraphQL Schema v2.4.0
85+
86+
Usage: node bin/graphdoc.js [OPTIONS]
87+
88+

89+
PTIONS]:
90+
-c, --config Configuration file [./package.json].
91+
-e, --endpoint Graphql http endpoint ["https://domain.com/graphql"].
92+
-x, --header HTTP header for request (use with --endpoint). ["Authorization: Token cb8795e7"].
93+
-q, --query HTTP querystring for request (use with --endpoint) ["token=cb8795e7"].
94+
-s, --schema, --schema-file Graphql Schema file ["./schema.json"].
95+
-p, --plugin Use plugins [default=graphdoc/plugins/default].
96+
-t, --template Use template [default=graphdoc/template/slds].
97+
-o, --output Output directory.
98+
-d, --data Inject custom data.
99+
-b, --base-url Base url for templates.
100+
-f, --force Delete outputDirectory if exists.
101+
-v, --verbose Output more information.
102+
-V, --version Show graphdoc version.
103+
-h, --help Print this help
104+

95105

96106
```
97107
@@ -100,117 +110,7 @@ And execute
100110
In graphdoc a plugin is simply an object that controls the content that is displayed
101111
on every page of your document.
102112
103-
This object should only implement the `PluginInterface`.
104-
105-
```typescript
106-
107-
/**
108-
* PluginInterface
109-
*/
110-
export interface PluginInterface {
111-
112-
/**
113-
* Return section elements that is going to be
114-
* inserted into the side navigation bar.
115-
*
116-
* @example plain javascript:
117-
* [
118-
* {
119-
* title: 'Schema',
120-
* items: [
121-
* {
122-
* text: 'Query',
123-
* href: './query.doc.html',
124-
* isActive: false
125-
* },
126-
* // ...
127-
* }
128-
* // ...
129-
* ]
130-
*
131-
* @example with graphdoc utilities:
132-
* import { NavigationSection, NavigationItem } from 'graphdoc/lib/utility';
133-
*
134-
* [
135-
* new NavigationSection('Schema', [
136-
* new NavigationItem('Query', ./query.doc.html', false)
137-
* ]),
138-
* // ...
139-
* ]
140-
*
141-
* @param {string} [buildForType] -
142-
* the name of the element for which the navigation section is being generated,
143-
* if it is `undefined it means that the index of documentation is being generated
144-
*/
145-
getNavigations?: (buildForType?: string) => NavigationSectionInterface[] | PromiseLike<NavigationSectionInterface[]>;
146-
147-
/**
148-
* Return section elements that is going to be
149-
* inserted into the main section.
150-
*
151-
* @example plain javascript:
152-
* [
153-
* {
154-
* title: 'GraphQL Schema definition',
155-
* description: 'HTML'
156-
* },
157-
* // ...
158-
* ]
159-
*
160-
* @example with graphdoc utilities:
161-
* import { DocumentSection } from 'graphdoc/lib/utility';
162-
*
163-
* [
164-
* new DocumentSection('GraphQL Schema definition', 'HTML'),
165-
* // ...
166-
* ]
167-
*
168-
* @param {string} [buildForType] -
169-
* the name of the element for which the navigation section is being generated,
170-
* if it is `undefined it means that the index of documentation is being generated
171-
*
172-
*/
173-
getDocuments?: (buildForType?: string) => DocumentSectionInterface[] | PromiseLike<DocumentSectionInterface[]>;
174-
175-
/**
176-
* Return a list of html tags that is going to be
177-
* inserted into the head tag of each page.
178-
*
179-
* @example
180-
* [
181-
* '<script src="https://code.jquery.com/jquery-3.1.1.min.js"></script>',
182-
* '<link href="https://fonts.googleapis.com/icon?family=Material+Icons" rel="stylesheet">',
183-
* ]
184-
*/
185-
getHeaders?: (buildForType?: string) => string[] | PromiseLike<string[]>;
186-
187-
/**
188-
* Return a list of abasolute path to files that is going to be
189-
* copied to the assets directory.
190-
*
191-
* Unlike the previous methods that are executed each time that a page generated,
192-
* this method is called a single time before starting to generate the documentation
193-
*
194-
* @example
195-
* [
196-
* '/local/path/to/my-custom-style.css',
197-
* '/local/path/to/my-custom-image.png',
198-
* ]
199-
*
200-
* there's will be copied to
201-
* /local/path/to/my-custom-style.css -> [OUTPUT_DIRETORY]/assets/my-custom-style.css
202-
* /local/path/to/my-custom-image.png -> [OUTPUT_DIRETORY]/assets/my-custom-image.png
203-
*
204-
* If you want to insert styles or scripts to the documentation,
205-
* you must combine this method with getHeaders
206-
*
207-
* @example
208-
* getAssets(): ['/local/path/to/my-custom-style.css']
209-
* getHeaders(): ['<link href="assets/my-custom-style.css" rel="stylesheet">']
210-
*/
211-
getAssets?: () => string[] | PromiseLike<string[]>;
212-
}
213-
```
113+
This object should only implement the [`PluginInterface`](https://github.com/2fd/graphdoc/blob/master/lib/interface.d.ts#L12-L117).
214114
215115
### Make a Plugin
216116
@@ -312,3 +212,10 @@ You can use the plugins in 2 ways.
312212
## Template
313213
314214
> TODO
215+
216+
217+
## Contributors
218+
219+
- [<img src="https://avatars2.githubusercontent.com/u/1301838?v=4" width="40"> bitliner](https://github.com/bitliner)
220+
- [<img src="https://avatars0.githubusercontent.com/u/605742?v=4" width="40"> kbariotis](https://github.com/kbariotis)
221+
- [<img src="https://avatars1.githubusercontent.com/u/2903325?v=4" width="40"> dnalborczyk](https://github.com/dnalborczyk)

0 commit comments

Comments
 (0)