docs(magidoc): add custom pages and appLogo [skip publish]

.gitignore

@@ -37,7 +37,7 @@ coverage/
 api/
 dist/
 codegen/
-docs/
+docs/generated-docs/
 
 ## Scripts
 scripts/tiers.ts

.prettierrc.cjs

@@ -13,7 +13,7 @@ module.exports = {
  }
  },
  {
- files: ['README.md'],
+ files: ['README.md', 'docs/pages/**/*.md'],
  options: {
  tabWidth: 2,
  useTabs: false,

magidoc.mjs → docs/magidoc.mjs

@@ -1,5 +1,7 @@
 import { fileURLToPath } from 'node:url';
 
+const { pages } = await import('./pages.mjs');
+
 const CommonDescription = 'Extensive Pokémon GraphQL API with data for all generations.';
 const CommonTitle = 'GraphQL Pokémon';
 const CommonURL = 'https://graphqlpokemon.js.org';
@@ -10,14 +12,19 @@ const CommonURL = 'https://graphqlpokemon.js.org';
 const config = {
  introspection: {
  type: 'sdl',
- paths: ['./graphql/*.graphql']
+ paths: ['./graphql/*.graphql'] // CWD is the root of the project, not the current docs/ directory
+ },
+ dev: {
+ watch: [fileURLToPath(new URL('./pages', import.meta.url)), fileURLToPath(new URL('./pages.mjs', import.meta.url))]
  },
  website: {
  template: 'carbon-multi-page',
- output: fileURLToPath(new URL('./docs', import.meta.url)),
+ output: fileURLToPath(new URL('./generated-docs', import.meta.url)),
  options: {
+ pages,
  appTitle: 'GraphQL Pokémon Docs',
  appFavicon: 'https://cdn.favware.tech/img/gqlp.png',
+ appLogo: 'https://cdn.favware.tech/img/gqlp-and-name.png',
  siteRoot: '/graphql-pokemon',
  externalLinks: [
  {

docs/pages.mjs

@@ -0,0 +1,66 @@
+/**
+ * MIT License
+ * Copyright (c) 2022 Sunny Pelletier
+ */
+
+import { readdir, readFile, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+/**
+ * Scans the directory for files and collects them
+ * @param {import('node:fs').PathLike} dir The directory to scan the files from
+ * @returns {Promise<Array<{ dir: boolean; name: string; path: string; }>>} The files in the directory
+ */
+async function getFiles(dir) {
+ /**
+ * @type Array<{ dir: boolean; name: string; path: string; }>
+ */
+ const result = [];
+ const dirAsPathString = dir instanceof URL ? fileURLToPath(dir) : dir;
+
+ const dirContents = await readdir(dir);
+
+ for (const item of dirContents) {
+ const currentPath = join(dirAsPathString, item);
+
+ const currentPathStat = await stat(currentPath);
+
+ result.push({
+ dir: currentPathStat.isDirectory(),
+ name: item,
+ path: currentPath
+ });
+ }
+
+ return result;
+}
+
+/**
+ * Get all items as page objects
+ * @param {{ dir: boolean; name: string; path: string; }} item The item to parse
+ * @returns {{ title: string; content: any }} Returns the item as a Page
+ */
+async function asPage(item) {
+ const title = item.name.split('.')[1];
+
+ if (item.dir) {
+ const filesInDirectory = await getFiles(item.path);
+
+ return {
+ title,
+ content: await Promise.all(filesInDirectory.map((item) => asPage(item)))
+ };
+ }
+
+ return {
+ title,
+ content: await readFile(item.path, { encoding: 'utf-8' })
+ };
+}
+
+const pagesDirectory = new URL('./pages', import.meta.url);
+
+const filesInPagesDirectory = await getFiles(pagesDirectory);
+
+export const pages = await Promise.all(filesInPagesDirectory.map((item) => asPage(item)));

docs/pages/01.Introduction/01.Welcome.md

@@ -0,0 +1,19 @@
+# Welcome
+
+Welcome to the `graphql-pokemon` project!
+
+This projects contains a GraphQL API for retrieving information about Pokémon.
+The API allows users to query for information about Pokémon, including their
+types, abilities, and moves. The data for the Pokémon is sourced from the
+popular video game series, provided by external sources such as
+[Smogon](https://www.smogon.com), [Serebii](https://serebii.net), and
+[Bulbapedia](https://bulbapedia.bulbagarden.net).
+
+The easiest way to get to know this API is to try it out in the
+[playground](https://graphqlpokemon.favware.tech/v7).
+
+For implementing the API in your own code, choose your preferred language and
+method of making Web requests. Beyond that point you will need to learn the
+GraphQL syntax, and the documentation on this website as well as the queries
+provided by the [playground](https://graphqlpokemon.favware.tech/v7) will help
+you get started.

docs/pages/01.Introduction/02.JavaScript Examples.md

@@ -0,0 +1,151 @@
+# JavaScript Examples
+
+_These examples are written as based on TypeScript. For JavaScript simply change
+out the imports to `require` syntax and remove any type information._
+
+## Using `Fetch`
+
+_note: for a working example see [dragonite]_
+
+```ts
+import type { Query } from '@favware/graphql-pokemon';
+
+interface GraphQLPokemonResponse<K extends keyof Omit<Query, '__typename'>> {
+ data: Record<K, Omit<Query[K], '__typename'>>;
+}
+
+fetch('https://graphqlpokemon.favware.tech/v7', {
+ method: 'POST',
+ headers: {
+ 'Content-Type': 'application/json'
+ },
+ body: JSON.stringify({
+ query: `
+ {
+ getPokemon(pokemon: dragonite) {
+ sprite
+ num
+ species
+ color
+ }
+ }
+ `
+ })
+})
+ .then((res) => res.json() as Promise<GraphQLPokemonResponse<'getPokemon'>>)
+ .then((json) => console.log(json.data));
+```
+
+## Using `Apollo Boost`
+
+_note: for a working example see [dexa]_
+
+```ts
+import type { Query, QueryGetFuzzyPokemonArgs } from '@favware/graphql-pokemon';
+import ApolloClient from 'apollo-boost';
+import fetch from 'cross-fetch';
+import gql from 'graphql-tag';
+
+type GraphQLPokemonResponse<K extends keyof Omit<Query, '__typename'>> = Record<
+ K,
+ Omit<Query[K], '__typename'>
+>;
+
+const getFuzzyPokemon = gql`
+ query getFuzzyPokemon($pokemon: String!) {
+ getFuzzyPokemon(pokemon: $pokemon) {
+ sprite
+ num
+ species
+ color
+ }
+ }
+`;
+
+const apolloClient = new ApolloClient({
+ uri: 'https://graphqlpokemon.favware.tech/v7',
+ fetch
+});
+
+const {
+ data: { getFuzzyPokemon: pokemonData }
+} = await apolloClient.query<
+ GraphQLPokemonResponse<'getFuzzyPokemon'>,
+ QueryGetFuzzyPokemonArgs
+>({
+ query: getFuzzyPokemon,
+ variables: { pokemon: 'dragonite' }
+});
+
+console.log(pokemonData);
+```
+
+## Using `Apollo Client React`
+
+**First setup your Apollo Client**
+
+```ts
+import { ApolloClient } from 'apollo-client';
+import { InMemoryCache } from 'apollo-cache-inmemory';
+import { HttpLink } from 'apollo-link-http';
+
+// Instantiate required constructor fields
+const cache = new InMemoryCache();
+const link = new HttpLink({
+ uri: 'https://graphqlpokemon.favware.tech/v7'
+});
+
+export const client = new ApolloClient({
+ // Provide required constructor fields
+ cache: cache,
+ link: link,
+
+ // Provide some optional constructor fields
+ name: 'graphql-pokemon-client',
+ version: '1.0',
+ queryDeduplication: false,
+ defaultOptions: {
+ watchQuery: {
+ fetchPolicy: 'cache-and-network'
+ }
+ }
+});
+```
+
+**Then use the client in your component**
+
+```ts
+import React from 'react';
+import gql from 'graphql-tag';
+import { useQuery } from '@apollo/react-hooks';
+import type { Query } from '@favware/graphql-pokemon';
+import { client } from './ApolloClient';
+
+interface GraphQLPokemonResponse<K extends keyof Omit<Query, '__typename'>> {
+ data: Record<K, Omit<Query[K], '__typename'>>;
+}
+
+const GET_POKEMON_DETAILS = gql`
+ {
+ getPokemon(pokemon: dragonite) {
+ sprite
+ num
+ species
+ color
+ }
+ }
+`;
+
+export const Pokemon: React.FC = () => {
+ const { loading, error, data } = useQuery<
+ GraphQLPokemonResponse<'getPokemon'>
+ >(GET_POKEMON_DETAILS, {
+ client: client
+ });
+
+ if (loading) return 'Loading...';
+ if (error) return `Error! ${error.message}`;
+
+ return <div> Insert how you want to display the data here </div>;
+};
+```

package.json

@@ -36,7 +36,7 @@
  "watch": "tsup --watch --onSuccess \"node scripts/on-build-success.mjs\"",
  "dev": "yarn build && yarn start",
  "clean": "node scripts/clean.mjs",
- "docs": "magidoc generate",
+ "docs": "magidoc generate -f ./docs/magidoc.mjs",
  "bump": "cliff-jumper",
  "check-update": "cliff-jumper --dry-run",
  "codegen": "graphql-codegen && npm-run-all -s \"typescript:*\"",
@@ -71,10 +71,10 @@
  "@skyra/jaro-winkler": "^1.1.0",
  "@swc/core": "^1.3.21",
  "@types/koa": "^2.13.5",
- "@types/node": "^18.11.10",
- "@typescript-eslint/eslint-plugin": "^5.45.0",
- "@typescript-eslint/parser": "^5.45.0",
- "@vitest/coverage-c8": "^0.25.3",
+ "@types/node": "^18.11.11",
+ "@typescript-eslint/eslint-plugin": "^5.45.1",
+ "@typescript-eslint/parser": "^5.45.1",
+ "@vitest/coverage-c8": "^0.25.5",
  "apollo-server-koa": "^3.11.1",
  "colorette": "^2.0.19",
  "cz-conventional-changelog": "^3.3.0",
@@ -83,16 +83,16 @@
  "eslint-plugin-prettier": "^4.2.1",
  "graphql-parse-resolve-info": "^4.12.3",
  "husky": "^8.0.2",
- "koa": "^2.13.4",
- "lint-staged": "^13.0.4",
+ "koa": "^2.14.1",
+ "lint-staged": "^13.1.0",
  "npm-run-all": "^4.1.5",
  "pinst": "^3.0.0",
  "prettier": "^2.8.0",
  "pretty-quick": "^3.1.3",
  "replace-in-file": "^6.3.5",
  "tsup": "^6.5.0",
  "typescript": "^4.9.3",
- "vitest": "^0.25.3"
+ "vitest": "^0.25.5"
  },
  "resolutions": {
  "ansi-regex": "^5.0.1",

tsconfig.eslint.json

@@ -1,4 +1,4 @@
 {
  "extends": "./tsconfig.base.json",
- "include": ["src", "scripts", "tests", "magidoc.mjs", "vitest.config.ts", "tsup.config.ts", "tsup.config-codegen.ts", ".prettierrc.cjs"]
+ "include": ["src", "scripts", "tests", "docs", "vitest.config.ts", "tsup.config.ts", "tsup.config-codegen.ts", ".prettierrc.cjs"]
 }