Upgrade docs theme (#553)

* Upgrade theme and remove h* tags * Move redirects file to the right place * Upgrade theme to v1
apollographql · May 29, 2019 · 855e8fd · 855e8fd
1 parent 395311e
commit 855e8fd
Show file tree

Hide file tree

Showing 12 changed files with 1,732 additions and 1,440 deletions.
diff --git a/docs/gatsby-config.js b/docs/gatsby-config.js
@@ -1,13 +1,12 @@
 module.exports = {
+  pathPrefix: '/docs/ios',
   __experimentalThemes: [
     {
       resolve: 'gatsby-theme-apollo-docs',
       options: {
         root: __dirname,
         subtitle: 'Apollo iOS Guide',
         description: 'A guide to using Apollo with iOS',
-        contentDir: 'docs/source',
-        basePath: '/docs/ios',
         githubRepo: 'apollographql/apollo-ios',
         sidebarCategories: {
           null: [

diff --git a/docs/package-lock.json b/docs/package-lock.json
diff --git a/docs/package.json b/docs/package.json
@@ -1,9 +1,11 @@
 {
   "scripts": {
-    "start": "gatsby develop"
+    "start": "rm -rf .cache && gatsby develop",
+    "build": "gatsby build",
+    "serve": "gatsby serve"
   },
   "dependencies": {
-    "gatsby": "2.7.1",
-    "gatsby-theme-apollo-docs": "0.3.3"
+    "gatsby": "^2.7.3",
+    "gatsby-theme-apollo-docs": "^1.0.0"
   }
 }
diff --git a/docs/source/api-reference.md b/docs/source/api-reference.md
@@ -1,5 +1,6 @@
 ---
 title: API Reference
+description: ''
 ---
 
 Please see [here](http://cocoadocs.org/docsets/Apollo/).
diff --git a/docs/source/fetching-queries.md b/docs/source/fetching-queries.md
@@ -10,7 +10,7 @@ Apollo iOS takes a schema and a set of `.graphql` files and uses these to genera
 
 > All `.graphql` files in your project (or the subset you specify as input to `apollo` if you customize the script you define as the code generation build phase) will be combined and treated as one big GraphQL document. That means fragments defined in one `.graphql` file are available to all other `.graphql` files for example, but it also means operation names and fragment names have to be unique and you will receive validation errors if they are not.
 
-<h2 id="creating-queries">Creating queries</h2>
+## Creating queries
 
 Queries are represented as instances of generated classes conforming to the `GraphQLQuery` protocol. Constructor arguments can be used to define query variables if needed. You pass a query object to `ApolloClient#fetch(query:)` to send the query to the server, execute it, and receive typed results.
 
@@ -38,7 +38,7 @@ The `error` parameter to the completion handler signals network or response form
 
 In addition to an optional `data` property, `result` contains an optional `errors` array with GraphQL errors (for more on this, see the sections on [error handling](https://facebook.github.io/graphql/#sec-Error-handling) and the [response format](https://facebook.github.io/graphql/#sec-Response-Format) in the GraphQL specification).
 
-<h2 id="typed-query-results">Typed query results</h2>
+## Typed query results
 
 Query results are defined as nested immutable structs that at each level only contain the properties defined in the corresponding part of the query definition. This means the type system won't allow you to access fields that are not actually fetched by the query, even if they *are* part of the schema.
 
@@ -97,9 +97,9 @@ apollo.fetch(query: HeroAndFriendsNamesQuery(episode: .empire)) { (result, error
 
 Because the above query won't fetch `appearsIn`, this property is not part of the returned result type and cannot be accessed here.
 
-<h2 id="cache-policy">Specifying a cache policy</h2>
+## Specifying a cache policy
 
-As explained in more detail in [the section on watching queries](watching-queries.html), Apollo iOS keeps a normalized client-side cache of query results and allows queries to be loaded from the cache.
+As explained in more detail in [the section on watching queries](/watching-queries/), Apollo iOS keeps a normalized client-side cache of query results and allows queries to be loaded from the cache.
 
 `fetch(query:)` takes an optional `cachePolicy` that allows you to specify when results should be fetched from the server, and when data should be loaded from the local cache.
 

diff --git a/docs/source/fragments.md b/docs/source/fragments.md
@@ -51,7 +51,7 @@ In most cases, you'll simply pass the whole fragment to a child view without nee
 cell.configure(with: hero?.fragments.heroDetails)
 ```
 
-<h2 id="type-conditions">Type conditions</h2>
+## Type conditions
 
 The GraphQL type system includes interfaces and unions as abstract types that object types can conform to. In the Star Wars example schema for example, both `Human`s and `Droid`s implement the `Character` interface. If we query for a hero, the result can be either a human or a droid, and if we want to access any type-specific properties we will have to use a fragment with a type condition:
 

diff --git a/docs/source/index.md → docs/source/index.mdx b/docs/source/index.md → docs/source/index.mdx
@@ -1,5 +1,6 @@
 ---
 title: Introduction
+description: A strongly-typed, caching GraphQL client for iOS, written in Swift
 ---
 
 [Apollo iOS](https://github.com/apollographql/apollo-ios) is a strongly-typed, caching GraphQL client for native iOS apps, written in Swift.
@@ -12,7 +13,7 @@ Apollo iOS does more than simply run your queries against a GraphQL server howev
 
 This combination of immutable models, one way data flow, and automatic consistency management, leads to a very powerful and elegant programming model that allows you to eliminate common glue code and greatly simplifies app development.
 
-<h2 id="getting-started">Getting Started</h2>
+## Getting Started
 
 [Front Page](https://github.com/apollographql/frontpage-ios-app) is the iOS version of the simple "Hello World" app that lives on our [developer site](http://dev.apollodata.com).
 
@@ -24,7 +25,7 @@ Apollo Client for JavaScript's [React integration](https://apollographql.com/doc
 
 We're excited about the prospects of further [unifying the clients for JavaScript, iOS and Android](https://blog.apollographql.com/one-graphql-client-for-javascript-ios-and-android-64993c1b7991), including sharing a cache between native and React Native.
 
-<h2 id="learn-more">Other resources</h2>
+## Other resources
 
 - [GraphQL.org](http://graphql.org) for an introduction and reference to the GraphQL itself, partially written and maintained by the Apollo team.
 - [Our website](http://www.apollodata.com/) to learn about Apollo open source and commercial tools.

diff --git a/docs/source/initialization.md b/docs/source/initialization.md
@@ -8,7 +8,7 @@ In most cases, you'll want to create a single shared instance of `ApolloClient`
 let apollo = ApolloClient(url: URL(string: "http://localhost:8080/graphql")!)
 ```
 
-<h2 id="adding-headers">Adding additional headers</h2>
+## Adding additional headers
 
 If you need to add additional headers to requests, to include authentication details for example, you can create your own `URLSessionConfiguration` and use this to configure an `HTTPNetworkTransport`. If you want to define the client as a global variable, you can use an immediately invoked closure here:
 

diff --git a/docs/source/installation.md b/docs/source/installation.md
@@ -14,7 +14,7 @@ Follow along with these steps (described in detail below) to use Apollo iOS in y
 1. Install the Xcode add-ons to get syntax highlighting for your `.graphql` files (optional)
 1. Create `.graphql` files with your queries or mutations and add them to your target
 
-<h2 id="installing-framework">Installing the Apollo framework</h2>
+## Installing the Apollo framework
 
 You can install `Apollo.framework` into your project using Carthage, CocoaPods, or by manually integrating it with Xcode.
 
@@ -57,7 +57,7 @@ You can install `Apollo.framework` into your project using Carthage, CocoaPods,
 
 You can also manually clone the [`apollo-ios` repository](https://github.com/apollostack/apollo-ios), drag `Apollo.xcodeproj` into your project or workspace, add a dependency on `Apollo.framework` to your target.
 
-<h2 id="adding-build-step">Adding a code generation build step</h2>
+## Adding a code generation build step
 
 In order to invoke `apollo` as part of the Xcode build process, create a build step that runs before "Compile Sources".
 
@@ -92,24 +92,24 @@ $APOLLO_FRAMEWORK_PATH/Versions/Current/Resources/check-and-run-apollo-cli.sh co
 
 The script above will invoke `apollo` through the `check-and-run-apollo-cli.sh` wrapper script, which is actually contained in the `Apollo.framework` bundle. The main reason for this is to check whether the version of `apollo` installed on your system is compatible with the framework version installed in your project, and to warn you if it isn't. Without this check, you could end up generating code that is incompatible with the runtime code contained in the framework.
 
-<h2 id="adding-schema">Adding a schema file to your target directory</h2>
+## Adding a schema file to your target directory
 
-You'll have to copy or [download a schema](downloading-schema.html) to your target directory before generating code.
+You'll have to copy or [download a schema](/downloading-schema/) to your target directory before generating code.
 
-Apollo iOS requires a GraphQL schema file as input to the code generation process. A schema file is a JSON file that contains the results of an an introspection query. Conventionally this file is called `schema.json`.  
+Apollo iOS requires a GraphQL schema file as input to the code generation process. A schema file is a JSON file that contains the results of an an introspection query. Conventionally this file is called `schema.json`.
 
-<h2 id="building-target">Build your target</h2>
+## Build your target
 
 At this point, you can try building your target in Xcode.  This will verify that the `schema.json` file can be found by the `apollo` script created above, otherwise you'll get a build error such as:
 > Cannot find GraphQL schema file [...]
 
-<h2 id="adding-generated-api">Adding the generated API file to your target</h2>
+## Adding the generated API file to your target
 
 1. Drag the generated `API.swift` file to your target.
 
 > Note that because Apollo iOS generates query-specific result types, `API.swift` will be mostly empty at this point unless you've already added some `.graphql` files with queries or mutations to your target directory.
 
-<h2 id="installing-xcode-add-ons">Installing the Xcode add-ons to get syntax highlighting</h2>
+## Installing the Xcode add-ons to get syntax highlighting
 
 1. Clone the [`xcode-apollo` repository](https://github.com/apollostack/xcode-apollo) to your computer.
 1. Close Xcode if it is currently running.
@@ -127,7 +127,7 @@ At this point, you can try building your target in Xcode.  This will verify that
 
 You may receive a warning when you first start up Xcode after installing these add-ons.
 
-<h2 id="creating-query-documents">Create `.graphql` files with your queries or mutations</h2>
+## Create `.graphql` files with your queries or mutations
 
 Apollo iOS generates code from queries and mutations contained in `.graphql` files in your target.
 

diff --git a/docs/source/mutations.md b/docs/source/mutations.md
@@ -39,7 +39,7 @@ apollo.perform(mutation: UpvotePostMutation(postId: postId)) { (result, error) i
 }
 ```
 
-<h2 id="fragments-in-mutation-results">Using fragments in mutation results</h2>
+## Using fragments in mutation results
 
 In many cases, you'll want to use mutation results to update your UI. Fragments can be a great way of sharing result handling between queries and mutations:
 
@@ -57,7 +57,7 @@ apollo.perform(mutation: UpvotePostMutation(postId: postId)) { (result, error) i
 }
 ```
 
-<h2 id="input-objects">Passing input objects</h2>
+## Passing input objects
 
 The GraphQL type system includes [input objects](http://graphql.org/learn/schema/#input-types) as a way to pass complex values to fields. Input objects are often defined as mutation variables, because they give you a compact way to pass in objects to be created:
 
@@ -75,7 +75,7 @@ let review = ReviewInput(stars: 5, commentary: "This is a great movie!")
 apollo.perform(mutation: CreateReviewForEpisodeMutation(episode: .jedi, review: review))
 ```
 
-<h2 id="designing-mutation-results">Designing mutation results</h2>
+## Designing mutation results
 
 When people talk about GraphQL, they often focus on the data fetching side of things, because that's where GraphQL brings the most value. Mutations can be pretty nice if done well, but the principles of designing good mutations, and especially good mutation result types, are not yet well-understood in the open source community. So when you are working with mutations it might often feel like you need to make a lot of application-specific decisions.
 

diff --git a/docs/source/watching-queries.md b/docs/source/watching-queries.md
@@ -4,7 +4,7 @@ title: Caching and watching queries
 
 As mentioned in the introduction, Apollo iOS does more than simply run your queries against a GraphQL server. It normalizes query results to construct a client-side cache of your data, which is kept up to date as further queries and mutations are run. This means your UI is always internally consistent, and can be kept fully up-to-date with the state on the server with the minimum number of queries required.
 
-<h2 id="watching-queries">Watching queries</h2>
+## Watching queries
 
 Watching a query is very similar to fetching a query. The main difference is that you don't just receive an initial result, but your result handler will be invoked whenever relevant data in the cache changes:
 
@@ -14,7 +14,7 @@ let watcher = apollo.watch(query: HeroNameQuery(episode: .empire)) { (result, er
 }
 ```
 
-<h2 id="normalization">Controlling normalization</h2>
+## Controlling normalization
 
 While Apollo can do basic caching based on the shape of GraphQL queries and their results, Apollo won't be able to associate objects fetched by different queries without additional information about the identities of the objects returned from the server. This is referred to as [cache normalization](http://dev.apollodata.com/core/how-it-works.html#normalize). You can read about our caching model in detail in our blog post, ["GraphQL Concepts Visualized"](https://medium.com/apollo-stack/the-concepts-of-graphql-bc68bd819be3).
 
@@ -26,13 +26,13 @@ apollo.cacheKeyForObject = { $0["id"] }
 
 > In some cases, just using `cacheKeyForObject` is not enough for your application UI to update correctly. For example, if you want to add something to a list of objects without refetching the entire list, or if there are some objects that to which you can't assign an object identifier, Apollo cannot automatically update existing queries for you.
 
-<h2 id="direct-cache-access">Direct cache access</h2>
+## Direct cache access
 
-Similarly to the [Apollo React API](https://www.apollographql.com/docs/react/advanced/caching.html#direct), you can directly read and update the cache as needed using Swift's [inout parameters](https://docs.swift.org/swift-book/LanguageGuide/Functions.html#ID173). This functionality is useful when performing mutations or receiving subscription data, as you should always update the local cache to ensure consistency with the operation that was just performed. The ability to write to the cache directly also prevents you from needing to re-fetch data over the network after a mutation is performed.
+Similarly to the [Apollo React API](https://www.apollographql.com/docs/react/advanced/caching/#direct), you can directly read and update the cache as needed using Swift's [inout parameters](https://docs.swift.org/swift-book/LanguageGuide/Functions.html#ID173). This functionality is useful when performing mutations or receiving subscription data, as you should always update the local cache to ensure consistency with the operation that was just performed. The ability to write to the cache directly also prevents you from needing to re-fetch data over the network after a mutation is performed.
 
-<h3 id="read">read</h3>
+### read
 
-The `read` function is similar to React Apollo's [`readQuery`](https://www.apollographql.com/docs/react/advanced/caching.html#readquery) method and will return the cached data for a given GraphQL query:
+The `read` function is similar to React Apollo's [`readQuery`](https://www.apollographql.com/docs/react/advanced/caching/#readquery) method and will return the cached data for a given GraphQL query:
 
 ```swift
 // Assuming we have defined an ApolloClient instance `client`:
@@ -46,9 +46,9 @@ client.store.withinReadTransaction { transaction in
 }
 ```
 
-<h3 id="update">update</h3>
+### update
 
-The `update` function is similar to React Apollo's [`writeQuery`](https://www.apollographql.com/docs/react/advanced/caching.html#writequery-and-writefragment) method and will update the Apollo cache and propagate changes to all listeners (queries using the `watch` method):
+The `update` function is similar to React Apollo's [`writeQuery`](https://www.apollographql.com/docs/react/advanced/caching/#writequery-and-writefragment) method and will update the Apollo cache and propagate changes to all listeners (queries using the `watch` method):
 
 ```swift
 // Assuming we have defined an ApolloClient instance `client`:

diff --git a/netlify.toml b/netlify.toml
@@ -1,6 +1,6 @@
 [build]
   base    = "docs/"
   publish = "docs/public/"
-  command = "gatsby build --prefix-paths && mkdir -p docs/ios && mv public/* docs/ios && mv docs public/"
+  command = "gatsby build --prefix-paths && mkdir -p docs/ios && mv public/* docs/ios && mv docs public/ && mv public/docs/ios/_redirects public"
 [build.environment]
   NPM_VERSION = "6"