Skip to content

Commit 5c55df7

Browse files
fgmfubhy
fgm
authored and
fubhy
committed
Documentation (drupal-graphql#22)
* ToC, a bit of layout for Gitbook. * Completed first version of installation page. * Contribution page for review.
1 parent 4bd0ff8 commit 5c55df7

File tree

8 files changed

+237
-46
lines changed

8 files changed

+237
-46
lines changed

‎.gitignore

+3
Original file line numberDiff line numberDiff line change
@@ -3,3 +3,6 @@ npm-debug.log
33

44
# PHPunit coverage
55
build
6+
7+
# GitBook
8+
_book

‎README.md

+34-46
Original file line numberDiff line numberDiff line change
@@ -1,62 +1,50 @@
1-
# GraphQL integration for Drupal 8
1+
# GraphQL for Drupal
22

33
[![Build Status](https://travis-ci.org/fubhy/graphql-drupal.svg?branch=8.x-3.x)](https://travis-ci.org/fubhy/graphql-drupal)
44

5-
This module generates and exposes a GraphQL schema for all content entity types.
5+
This module generates and exposes a [GraphQL] schema for [Drupal 8] entities, and
6+
allows you to expose your own custom schema in a consistent way and with minimal
7+
effort.
68

7-
Project homepage: https://www.drupal.org/project/graphql
9+
It is probably the easiest way to build headless Drupal sites using the popular
10+
[React] / [Relay] couple for the front-end, and on top of the traditional fast
11+
Drupal site building for the content modeling and management.
812

9-
## Installation
13+
[Drupal 8]: https://www.drupal.org/8
14+
[GraphQL]: http://graphql.org/
15+
[React]: https://facebook.github.io/react/
16+
[Relay]: https://facebook.github.io/relay/
1017

11-
In order to install this module, since we are currently using a fork of the library that this module depends on, you
12-
have to specify a custom repository in your composer.json.
1318

14-
```
15-
"repositories": [
16-
{
17-
"type": "package",
18-
"package": {
19-
"name": "youshido/graphql",
20-
"version": "dev-drupal",
21-
"source": {
22-
"url": "https://github.com/fubhy/GraphQL.git",
23-
"type": "git",
24-
"reference": "drupal"
25-
}
26-
}
27-
}
28-
]
29-
```
19+
## Features
3020

31-
After adding this to your composer.json, you can run "composer require drupal/graphql:8.x-3.x".
21+
### Built-in schema
3222

33-
## Contributing
23+
By default, the module exposes all content and configuration entities as a
24+
Relay-compliant schema making the whole Drupal entity reference graph model
25+
available to clients: entities, ids and references.
26+
27+
It provides a fully data-based process, which does not trigger the theme system,
28+
and includes full cacheability metadata for low overhead.
3429

35-
For some time, development will happen on GitHub using the pull request model:
36-
in case you are not familiar with that, please take a few minutes to read the
37-
[GitHub article](https://help.github.com/articles/using-pull-requests) on using
38-
pull requests.
3930

40-
There are a few conventions that should be followed when contributing:
31+
### Developer experience
4132

42-
* Always create an issue in the [drupal.org GraphQL issue queue](https://www.drupal.org/project/issues/graphql)
43-
for every pull request you are working on.
44-
* Always cross-reference the Issue in the Pull Request and the Pull Request in
45-
the issue.
46-
* Always create a new branch for every pull request: its name should contain a
47-
brief summary of the ticket and its issue id, e.g **readme-2276369**.
48-
* Try to keep the history of your pull request as clean as possible by squashing
49-
your commits: you can look at the [Symfony documentation](http://symfony.com/doc/current/cmf/contributing/commits.html)
50-
or at the [Git book](http://git-scm.com/book/en/Git-Tools-Rewriting-History#Changing-Multiple-Commit-Messages)
51-
for more information on how to do that.
33+
The module is meant as a basis for custom development rather than pure site
34+
building. As such, at this point it only exposes entity identifiers and labels,
35+
leaving it up to you as a developer to choose whether/how to expose fields and
36+
non-entity data. To help you with this task, it provides base objects you only
37+
need to extend to define your own schema.
5238

53-
## Executing the automated tests
39+
For ease of development, it includes the [GraphiQL] in-browser IDE, already
40+
configured for Drupal in authenticated mode.
5441

55-
This module comes with PHPUnit tests. You need a working Drupal 8 installation
56-
and a checkout of the GraphQL module in the modules folder.
42+
[GraphiQL]: https://github.com/graphql/graphiql
5743

58-
cd /path/to/drupal-8/core
59-
../vendor/bin/phpunit ../modules/graphql/tests/src/Unit
60-
../vendor/bin/phpunit ../modules/graphql/tests/src/Integration
6144

62-
You can also execute the test cases from the web interface at ``/admin/config/development/testing``.
45+
## Resources
46+
47+
* Documentation: https://www.gitbook.com/book/fgm/graphql-for-drupal
48+
* Project homepage: https://www.drupal.org/project/graphql
49+
* Contributing: https://github.com/fubhy/graphql-drupal
50+

‎book.json

+3
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
{
2+
"root": "./doc"
3+
}

‎doc/README.md

+48
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
# GraphQL for Drupal
2+
3+
This module generates and exposes a [GraphQL] schema for [Drupal 8] entities, and
4+
allows you to expose your own custom schema in a consistent way and with minimal
5+
effort.
6+
7+
It is probably the easiest way to build headless Drupal sites using the popular
8+
[React] / [Relay] couple for the front-end, and on top of the traditional fast
9+
Drupal site building for the content modeling and management.
10+
11+
[Drupal 8]: https://www.drupal.org/8
12+
[GraphQL]: http://graphql.org/
13+
[React]: https://facebook.github.io/react/
14+
[Relay]: https://facebook.github.io/relay/
15+
16+
17+
## Features
18+
19+
### Built-in schema
20+
21+
By default, the module exposes all content and configuration entities as a
22+
Relay-compliant schema making the whole Drupal entity reference graph model
23+
available to clients: entities, ids and references.
24+
25+
It provides a fully data-based process, which does not trigger the theme system,
26+
and includes full cacheability metadata for low overhead.
27+
28+
29+
### Developer experience
30+
31+
The module is meant as a basis for custom development rather than pure site
32+
building. As such, at this point it only exposes entity identifiers and labels,
33+
leaving it up to you as a developer to choose whether/how to expose fields and
34+
non-entity data. To help you with this task, it provides base objects you only
35+
need to extend to define your own schema.
36+
37+
For ease of development, it includes the [GraphiQL] in-browser IDE, already
38+
configured for Drupal in authenticated mode.
39+
40+
[GraphiQL]: https://github.com/graphql/graphiql
41+
42+
43+
## Resources
44+
45+
* Documentation: https://www.gitbook.com/book/fgm/graphql-for-drupal
46+
* Project homepage: https://www.drupal.org/project/graphql
47+
* Contributing: https://github.com/fubhy/graphql-drupal
48+

‎doc/SUMMARY.md

+21
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
# Summary
2+
3+
* [Getting started](README)
4+
* [Installing](install/README.md)
5+
* [Exploring (TODO)](start/graphiql.md)
6+
* [Running tests (REVIEW)](tests/README.md)
7+
* [Concepts (TODO)](concepts/README.md)
8+
* [Decoupling Drupal (TODO)](concepts/headless.md)
9+
* [GraphQL for Drupal (TODO)](concepts/drupal.md)
10+
* [Front-end (TODO)](consumer/README.md)
11+
* [Full drupal (TODO)](front/drupal.md)
12+
* [Symfony 3 (TODO)](consumer/sf3.md)
13+
* [Vanilla React (TODO)](front/js.md)
14+
* [React + Relay (TODO)](front/relay.md)
15+
* [Back-end (TODO)](back/README.md)
16+
* [Builtin schema and fields (TODO)](back/schema.md)
17+
* [The PHP library (TODO)](back/youshido.md)
18+
* [Exposing new fields (TODO)](back/fields.md)
19+
* [Exposing new types (TODO)](back/types.md)
20+
* [Debugging (TODO)](back/debug.md)
21+
* [Contributing (REVIEW)](contrib/README.md)

‎doc/contrib/README.md

+33
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
# Contributing
2+
3+
For some time, development will happen on GitHub using the pull request model:
4+
in case you are not familiar with that, please take a few minutes to read the
5+
[GitHub article](https://help.github.com/articles/using-pull-requests) on using
6+
pull requests.
7+
8+
There are a few conventions that should be followed when contributing:
9+
10+
* Always create an issue in the [drupal.org GraphQL issue queue](https://www.drupal.org/project/issues/graphql)
11+
for every pull request you are working on.
12+
* Always cross-reference the Issue in the Pull Request and the Pull Request in
13+
the issue.
14+
* Always create a new branch for every pull request: its name should contain a
15+
brief summary of the ticket and its issue id, e.g **readme-2276369**.
16+
* Try to keep the history of your pull request as clean as possible by squashing
17+
your commits: you can look at the [Symfony documentation](http://symfony.com/doc/current/cmf/contributing/commits.html)
18+
or at the [Git book](http://git-scm.com/book/en/Git-Tools-Rewriting-History#Changing-Multiple-Commit-Messages)
19+
for more information on how to do that.
20+
21+
## Documentation
22+
23+
Documentation is maintained in the `doc` directory in [GitBook] format, and can be edited just like code issues with the pull request process.
24+
25+
[GitBook]: https://www.gitbook.com/
26+
27+
To check a local copy of documentation while working on it, install Gitbook locally, and type:
28+
29+
$ cd (your_drupal_site)
30+
$ cd modules/contrib/graphql
31+
$ gitbook serve
32+
33+
You then have documentation available on `http://localhost:4000/` with live-reload when you edit it.

‎doc/install/README.md

+83
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,83 @@
1+
# Installing
2+
3+
The simple way to install the module and its dependency is to use Composer, assuming you installed Drupal itself as described on [Using Composer to manage Drupal site dependencies](https://www.drupal.org/node/2718229).
4+
5+
## Preparing your Drupal instance
6+
7+
If you used the `drupal-composer/drupal-project` template, skip directly to step
8+
"[Adding the module](#adding-the-module)" below.
9+
10+
Otherwise, if you used the `drupal/drupal` method - e.g. by
11+
just cloning Drupal from its git repository - you have to add the
12+
"[installer paths]" configuration, by adding this fragment to your
13+
`composer.json` at the first level of the file:
14+
15+
"extra": {
16+
"installer-paths": {
17+
"modules/contrib/{$name}": ["type:drupal-module"],
18+
"modules/custom/{$name}": ["type:drupal-custom-module"],
19+
"profiles/contrib/{$name}": ["type:drupal-profile"],
20+
"themes/contrib/{$name}": ["type:drupal-theme"],
21+
"themes/custom/{$name}": ["type:drupal-custom-theme"]
22+
}
23+
}
24+
25+
This will ensure that the GraphQL module is correctly installed in the
26+
`modules/contrib/graphql` directory. Without this configuration, the module
27+
would default to being installed in `modules/graphql`, which is not the
28+
recommended practice.
29+
30+
[installer paths]: https://www.drupal.org/node/2718229#installer-dirs
31+
32+
33+
## Adding the module
34+
35+
Until the module is stable enough to have releases on drupal.org, its
36+
development versions are located on
37+
[https://github.com/fubhy/graphql-drupal](https://github.com/fubhy/graphql-drupal)
38+
which has no entry on [Packagist](https://packagist.org/search/). This means you
39+
need to tell Composer whence to download the module.
40+
41+
To do this, edit your `composer.json` file, and add the Drupal GraphQL
42+
repository location, at the first level of the file:
43+
44+
"repositories": [
45+
{
46+
"type": "vcs",
47+
"url": "https://github.com/fubhy/graphql-drupal"
48+
}
49+
],
50+
51+
Ensure you can run [Composer](https://getcomposer.org/download/). Then, go to
52+
the command line, and type (the `$ ` is your shell prompt, do not type it):
53+
54+
$ cd (the_project_root_directory)
55+
$ composer require drupal/graphql:8.x-3.x
56+
57+
This will take some time, and end by something like:
58+
59+
[...snip...]
60+
Writing lock file
61+
Generating autoload files
62+
> Drupal\Core\Composer\Composer::preAutoloadDump
63+
> Drupal\Core\Composer\Composer::ensureHtaccess
64+
$
65+
66+
At this point, all is ready, you can just enable the GraphQL module from the
67+
Drupal UI, Drush or Drupal console.
68+
69+
70+
## Checking installation
71+
72+
You can check that the installation process succeeded, by ensuring the module
73+
and its dependency are present:
74+
75+
ls -d vendor/youshido/graphql modules/contrib/graphql/
76+
77+
This should return something like this:
78+
79+
modules/contrib/graphql/ vendor/youshido/graphql
80+
81+
If you do not obtain these two paths, something went wrong with the Composer
82+
installation process, and you will need to fix it before you can enable the
83+
module.

‎doc/tests/README.md

+12
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
# Executing the automated tests
2+
3+
[![Build Status](https://travis-ci.org/fubhy/graphql-drupal.svg?branch=8.x-3.x)](https://travis-ci.org/fubhy/graphql-drupal)
4+
5+
This module comes with PHPUnit tests. You need a working Drupal 8 installation
6+
and a checkout of the GraphQL module in the modules folder.
7+
8+
cd /path/to/drupal-8/core
9+
../vendor/bin/phpunit ../modules/graphql/tests/src/Unit
10+
../vendor/bin/phpunit ../modules/graphql/tests/src/Integration
11+
12+
You can also execute the test cases from the web interface at ``/admin/config/development/testing``.

0 commit comments

Comments
 (0)