Skip to content

Commit

Permalink
Don't hard-wrap Markdown documents
Browse files Browse the repository at this point in the history
Summary:
When preparing the 0.9.1 release notes in `CHANGLOG.md` and previewing them on GitHub, I noticed some awkward wrapping in the rendered HTML near places where I had put hard line breaks in the file. This was fixed by not wrapping the 0.9.1 chunk of the release notes.

In this commit I've gone back and unwrapped all the Markdown files where we were hard-wrapping (the vast majority already don't hardwrap).

I was too lazy to visually inspect all the files, so I identified the likely candidates with this snippet of Ruby:

```
Dir['docs/*'].map{|d|File.read(d).lines.max_by{|l|l.size}}.map(&:size)
```

Which returned a list of the longest line of all files in "docs/":

```
=> [518, 448, 170, 423, 310, 181, 208, 204, 269, 81, 98, 79, 80, 112, 404,
467, 557, 269, 312, 325, 391, 177, 224, 172, 339, 186, 871, 306, 767, 401,
211, 153]
```

The obvious candidates were the chunk in the middle with lengths 81, 98, 79, 80 and 112, corresponding to the GraphQL docs, and sure enough, they were all hard-wrapped. Unwrapped by mashing `J` mindlessly in Vim.
Closes #1240

Reviewed By: kassens

Differential Revision: D3484515

Pulled By: wincent

fbshipit-source-id: 12e888a31fe18056a4f3b7094f4c8544aefeb367
  • Loading branch information
wincent authored and Facebook Github Bot 1 committed Jun 24, 2016
1 parent ee9924c commit a3075fa
Show file tree
Hide file tree
Showing 6 changed files with 89 additions and 259 deletions.
234 changes: 64 additions & 170 deletions CHANGELOG.md

Large diffs are not rendered by default.

32 changes: 7 additions & 25 deletions docs/GraphQL-Connections.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,10 +8,7 @@ indent: true
next: graphql-mutations
---

A faction has many ships in the Star Wars universe. Relay contains functionality
to make manipulating one-to-many relationships easy, using a standardized way
of expressing these one-to-many relationships. This standard connection
model offers ways of slicing and paginating through the connection.
A faction has many ships in the Star Wars universe. Relay contains functionality to make manipulating one-to-many relationships easy, using a standardized way of expressing these one-to-many relationships. This standard connection model offers ways of slicing and paginating through the connection.

Let's take the rebels, and ask for their first ship:

Expand Down Expand Up @@ -49,10 +46,7 @@ yields
}
```

That used the `first` argument to `ships` to slice the result set down to the
first one. But what if we wanted to paginate through it? On each edge, a cursor
will be exposed that we can use to paginate. Let's ask for the first two this
time, and get the cursor as well:
That used the `first` argument to `ships` to slice the result set down to the first one. But what if we wanted to paginate through it? On each edge, a cursor will be exposed that we can use to paginate. Let's ask for the first two this time, and get the cursor as well:

```
query MoreRebelShipsQuery {
Expand Down Expand Up @@ -96,10 +90,7 @@ and we get back
}
```

Notice that the cursor is a base64 string. That's the pattern from earlier: the
server is reminding us that this is an opaque string. We can pass this string
back to the server as the `after` argument to the `ships` field, which will let
us ask for the next three ships after the last one in the previous result:
Notice that the cursor is a base64 string. That's the pattern from earlier: the server is reminding us that this is an opaque string. We can pass this string back to the server as the `after` argument to the `ships` field, which will let us ask for the next three ships after the last one in the previous result:

```
query EndOfRebelShipsQuery {
Expand Down Expand Up @@ -181,12 +172,7 @@ yields
}
```

Hm. There were no more ships; guess there were only five in the system for
the rebels. It would have been nice to know that we'd reached the
end of the connection, without having to do another round trip in order
to verify that. The connection model exposes this capability with a type
called `PageInfo`. So let's issue the two queries that got us ships again,
but this time ask for `hasNextPage`:
Hm. There were no more ships; guess there were only five in the system for the rebels. It would have been nice to know that we'd reached the end of the connection, without having to do another round trip in order to verify that. The connection model exposes this capability with a type called `PageInfo`. So let's issue the two queries that got us ships again, but this time ask for `hasNextPage`:

```
query EndOfRebelShipsQuery {
Expand Down Expand Up @@ -265,12 +251,8 @@ and we get back
}
```

So on the first query for ships, GraphQL told us there was a next page,
but on the next one, it told us we'd reached the end of the connection.
So on the first query for ships, GraphQL told us there was a next page, but on the next one, it told us we'd reached the end of the connection.

Relay uses all of this functionality to build out abstractions around
connections, to make these easy to work with efficiently without having
to manually manage cursors on the client.
Relay uses all of this functionality to build out abstractions around connections, to make these easy to work with efficiently without having to manually manage cursors on the client.

Complete details on how the server should behave are
available in the [GraphQL Cursor Connections](../graphql/connections.htm) spec.
Complete details on how the server should behave are available in the [GraphQL Cursor Connections](../graphql/connections.htm) spec.
14 changes: 2 additions & 12 deletions docs/GraphQL-FurtherReading.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,16 +8,6 @@ indent: true
next: api-reference-relay
---

This concludes the overview of the GraphQL Relay Specifications. For the
detailed requirements of a Relay-compliant GraphQL server, a more formal
description of the [Relay cursor connection](../graphql/connections.htm) model,
the [Relay global object identification](../graphql/objectidentification.htm)
model, and the [Relay input object mutation](../graphql/mutations.htm) are all
available.
This concludes the overview of the GraphQL Relay Specifications. For the detailed requirements of a Relay-compliant GraphQL server, a more formal description of the [Relay cursor connection](../graphql/connections.htm) model, the [Relay global object identification](../graphql/objectidentification.htm) model, and the [Relay input object mutation](../graphql/mutations.htm) are all available.

To see code implementing the specification, the
[GraphQL.js Relay library](https://github.com/graphql/graphql-relay-js) provides
helper functions for creating nodes, connections, and mutations; that
repository's [`__tests__`](https://github.com/graphql/graphql-relay-js/tree/master/src/__tests__)
folder contains an implementation of the above example as integration tests for
the repository.
To see code implementing the specification, the [GraphQL.js Relay library](https://github.com/graphql/graphql-relay-js) provides helper functions for creating nodes, connections, and mutations; that repository's [`__tests__`](https://github.com/graphql/graphql-relay-js/tree/master/src/__tests__) folder contains an implementation of the above example as integration tests for the repository.
16 changes: 4 additions & 12 deletions docs/GraphQL-Mutations.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,17 +8,11 @@ indent: true
next: graphql-further-reading
---

Relay uses a common pattern for mutations, where they are root fields on the
mutation type with a single argument, `input`, and where the input and output
both contain a client mutation identifier used to reconcile requests and
responses.
Relay uses a common pattern for mutations, where they are root fields on the mutation type with a single argument, `input`, and where the input and output both contain a client mutation identifier used to reconcile requests and responses.

By convention, mutations are named as verbs, their inputs are the name with
"Input" appended at the end, and they return an object that is the name with
"Payload" appended.
By convention, mutations are named as verbs, their inputs are the name with "Input" appended at the end, and they return an object that is the name with "Payload" appended.

So for our `introduceShip` mutation, we create two types: `IntroduceShipInput`
and `IntroduceShipPayload`:
So for our `introduceShip` mutation, we create two types: `IntroduceShipInput` and `IntroduceShipPayload`:

```
input IntroduceShipInput {
Expand Down Expand Up @@ -80,6 +74,4 @@ and we'll get this result:
}
```

Complete details on how the server should behave are
available in the [GraphQL Input Object Mutations](../graphql/mutations.htm)
spec.
Complete details on how the server should behave are available in the [GraphQL Input Object Mutations](../graphql/mutations.htm) spec.
27 changes: 6 additions & 21 deletions docs/GraphQL-ObjectIdentification.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,14 +8,9 @@ indent: true
next: graphql-connections
---

Both `Faction` and `Ship` have identifiers that we can use to refetch them. We
expose this capability to Relay through the `Node` interface and the `node`
field on the root query type.
Both `Faction` and `Ship` have identifiers that we can use to refetch them. We expose this capability to Relay through the `Node` interface and the `node` field on the root query type.

The `Node` interface contains a single field, `id`, which is a `ID!`. The
`node` root field takes a single argument, a `ID!`, and returns a `Node`.
These two work in concert to allow refetching; if we pass the `id` returned in
that field to the `node` field, we get the object back.
The `Node` interface contains a single field, `id`, which is a `ID!`. The `node` root field takes a single argument, a `ID!`, and returns a `Node`. These two work in concert to allow refetching; if we pass the `id` returned in that field to the `node` field, we get the object back.

Let's see this in action, and query for the ID of the rebels:

Expand Down Expand Up @@ -63,8 +58,7 @@ returns
}
```

If we do the same thing with the Empire, we'll find that it returns a different
ID, and we can refetch it as well:
If we do the same thing with the Empire, we'll find that it returns a different ID, and we can refetch it as well:

```
query EmpireQuery {
Expand Down Expand Up @@ -110,17 +104,8 @@ yields
}
```

The `Node` interface and `node` field assume globally unique IDs for this
refetching. A system without globally unique IDs can usually synthesize them
by combining the type with the type-specific ID, which is what was done
in this example.
The `Node` interface and `node` field assume globally unique IDs for this refetching. A system without globally unique IDs can usually synthesize them by combining the type with the type-specific ID, which is what was done in this example.

The IDs we got back were base64 strings. IDs are designed to be opaque (the
only thing that should be passed to the `id` argument on `node` is the
unaltered result of querying `id` on some object in the system), and base64ing
a string is a useful convention in GraphQL to remind viewers that the string is
an opaque identifier.
The IDs we got back were base64 strings. IDs are designed to be opaque (the only thing that should be passed to the `id` argument on `node` is the unaltered result of querying `id` on some object in the system), and base64ing a string is a useful convention in GraphQL to remind viewers that the string is an opaque identifier.

Complete details on how the server should behave are
available in the
[GraphQL Object Identification](../graphql/objectidentification.htm) spec.
Complete details on how the server should behave are available in the [GraphQL Object Identification](../graphql/objectidentification.htm) spec.
25 changes: 6 additions & 19 deletions docs/GraphQL-RelaySpecification.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,38 +9,25 @@ next: graphql-object-identification

# Getting Started

The three core assumptions that Relay makes about a GraphQL server are that it
provides:
The three core assumptions that Relay makes about a GraphQL server are that it provides:

1. A mechanism for refetching an object.
2. A description of how to page through connections.
3. Structure around mutations to make them predictable.

This example demonstrates all three of these assumptions.

This example is not comprehensive, but it is designed to quickly introduce
these core assumptions, to provide some context before diving into
the more detailed specification or the library.
This example is not comprehensive, but it is designed to quickly introduce these core assumptions, to provide some context before diving into the more detailed specification or the library.

The premise of the example is that we want to use GraphQL to query for
information about ships and factions in the original Star Wars
trilogy.
The premise of the example is that we want to use GraphQL to query for information about ships and factions in the original Star Wars trilogy.

It is assumed that the reader is already familiar with GraphQL; if not,
the README for [GraphQL.js](https://github.com/graphql/graphql-js) is a
good place to start.
It is assumed that the reader is already familiar with GraphQL; if not, the README for [GraphQL.js](https://github.com/graphql/graphql-js) is a good place to start.

It is also assumed that the reader is already familiar with Star Wars; if not,
the 1977 version of Star Wars is a good place to start, though the 1997
Special Edition will serve for the purposes of this document.
It is also assumed that the reader is already familiar with Star Wars; if not, the 1977 version of Star Wars is a good place to start, though the 1997 Special Edition will serve for the purposes of this document.

## Schema

The schema described below will be used to demonstrate the functionality
that a GraphQL server used by Relay should implement. The two core types
are a faction and a ship in the Star Wars universe, where a faction
has many ships associated with it. The schema below is the output of the
GraphQL.js [`schemaPrinter`](https://github.com/graphql/graphql-js/blob/master/src/utilities/schemaPrinter.js).
The schema described below will be used to demonstrate the functionality that a GraphQL server used by Relay should implement. The two core types are a faction and a ship in the Star Wars universe, where a faction has many ships associated with it. The schema below is the output of the GraphQL.js [`schemaPrinter`](https://github.com/graphql/graphql-js/blob/master/src/utilities/schemaPrinter.js).

```
interface Node {
Expand Down

0 comments on commit a3075fa

Please sign in to comment.