From 87ab614fd9cb887561cd1fb0848ec98934dc1fdd Mon Sep 17 00:00:00 2001 From: Jesse Alan Johnson Date: Wed, 23 Sep 2020 04:53:32 -0400 Subject: [PATCH] document cleaning - tutorial quickstarts (#2520) * Formatting & spelling * Update quickstart-app-plugin.md * adding md's to contrib folder --- .../quickstart-app-plugin/ExampleComponent.md | 58 ++++++ .../ExampleFetchComponent.md | 111 ++++++++++ docs/tutorials/quickstart-app-auth.md | 9 +- docs/tutorials/quickstart-app-plugin.md | 192 +----------------- 4 files changed, 185 insertions(+), 185 deletions(-) create mode 100644 contrib/docs/tutorials/quickstart-app-plugin/ExampleComponent.md create mode 100644 contrib/docs/tutorials/quickstart-app-plugin/ExampleFetchComponent.md diff --git a/contrib/docs/tutorials/quickstart-app-plugin/ExampleComponent.md b/contrib/docs/tutorials/quickstart-app-plugin/ExampleComponent.md new file mode 100644 index 0000000000..855608c8b1 --- /dev/null +++ b/contrib/docs/tutorials/quickstart-app-plugin/ExampleComponent.md @@ -0,0 +1,58 @@ +### Source repo: https://github.com/johnson-jesse/simple-backstage-app-plugin + +ExampleComponent.tsx reference + +```tsx +import React, { FC } from 'react'; +import { Typography, Grid } from '@material-ui/core'; +import { + InfoCard, + Header, + Page, + pageTheme, + Content, + ContentHeader, + HeaderLabel, + SupportButton, + identityApiRef, +} from '@backstage/core'; +import { useApi } from '@backstage/core-api'; +import ExampleFetchComponent from '../ExampleFetchComponent'; + +const ExampleComponent: FC<{}> = () => { + const identityApi = useApi(identityApiRef); + const userId = identityApi.getUserId(); + const profile = identityApi.getProfile(); + + return ( + +
+ + +
+ + + A description of your plugin goes here. + + + + + + {`${profile.displayName} | ${profile.email}`} + + + + + + + + + + ); +}; + +export default ExampleComponent; +``` diff --git a/contrib/docs/tutorials/quickstart-app-plugin/ExampleFetchComponent.md b/contrib/docs/tutorials/quickstart-app-plugin/ExampleFetchComponent.md new file mode 100644 index 0000000000..08d14e8c4c --- /dev/null +++ b/contrib/docs/tutorials/quickstart-app-plugin/ExampleFetchComponent.md @@ -0,0 +1,111 @@ +### Source repo: https://github.com/johnson-jesse/simple-backstage-app-plugin + +ExampleFetchComponent.tsx reference + +```tsx +import React, { FC } from 'react'; +import { useAsync } from 'react-use'; +import Alert from '@material-ui/lab/Alert'; +import { + Table, + TableColumn, + Progress, + githubAuthApiRef, +} from '@backstage/core'; +import { useApi } from '@backstage/core-api'; +import { graphql } from '@octokit/graphql'; + +const query = `{ + viewer { + repositories(first: 100) { + totalCount + nodes { + name + createdAt + description + diskUsage + isFork + } + pageInfo { + endCursor + hasNextPage + } + } + } +}`; + +type Node = { + name: string; + createdAt: string; + description: string; + diskUsage: number; + isFork: boolean; +}; + +type Viewer = { + repositories: { + totalCount: number; + nodes: Node[]; + pageInfo: { + endCursor: string; + hasNextPage: boolean; + }; + }; +}; + +type DenseTableProps = { + viewer: Viewer; +}; + +export const DenseTable: FC = ({ viewer }) => { + const columns: TableColumn[] = [ + { title: 'Name', field: 'name' }, + { title: 'Created', field: 'createdAt' }, + { title: 'Description', field: 'description' }, + { title: 'Disk Usage', field: 'diskUsage' }, + { title: 'Fork', field: 'isFork' }, + ]; + + return ( + + ); +}; + +const ExampleFetchComponent: FC<{}> = () => { + const auth = useApi(githubAuthApiRef); + + const { value, loading, error } = useAsync(async (): Promise => { + const token = await auth.getAccessToken(); + + const gqlEndpoint = graphql.defaults({ + // Uncomment baseUrl if using enterprise + // baseUrl: 'https://github.MY-BIZ.com/api', + headers: { + authorization: `token ${token}`, + }, + }); + const { viewer } = await gqlEndpoint(query); + return viewer; + }, []); + + if (loading) return ; + if (error) return {error.message}; + if (value && value.repositories) return ; + + return ( +
+ ); +}; + +export default ExampleFetchComponent; +``` diff --git a/docs/tutorials/quickstart-app-auth.md b/docs/tutorials/quickstart-app-auth.md index 2615e37633..82f9cab537 100644 --- a/docs/tutorials/quickstart-app-auth.md +++ b/docs/tutorials/quickstart-app-auth.md @@ -187,10 +187,11 @@ builder.add( ); ``` -> Start the backend and frontend as before. When the browser loads, you should -> be presented with a login page for GitHub. Login as usual with your GitHub -> account. If this is your first time, you will be asked to authorize and then -> are redirected to the catalog page if all is well. +8. Start the backend and frontend as before + +When the browser loads, you should be presented with a login page for GitHub. +Login as usual with your GitHub account. If this is your first time, you will be +asked to authorize and then are redirected to the catalog page if all is well. # Where to go from here diff --git a/docs/tutorials/quickstart-app-plugin.md b/docs/tutorials/quickstart-app-plugin.md index 28efb2a007..51a7f8ded6 100644 --- a/docs/tutorials/quickstart-app-plugin.md +++ b/docs/tutorials/quickstart-app-plugin.md @@ -34,7 +34,7 @@ title: Adding Custom Plugin to Existing Monorepo App 1. When the process finishes, let's start the backend: `yarn --cwd packages/backend start` 1. If you see errors starting, refer to - [Auth Configuration](https://github.com/johnson-jesse/simple-backstage-app/blob/master/README.md#the-auth-configuration) + [Auth Configuration](https://backstage.io/docs/tutorials/quickstart-app-auth#the-auth-configuration) for more information on environment variables. 1. And now the frontend, from a new terminal window and the root of your project: `yarn start` @@ -119,67 +119,10 @@ If everything is saved, you should see your name, id, and email on the github-playground page. Our data accessed is synchronous. So we just grab and go. +https://github.com/spotify/backstage/tree/master/contrib + 6. Here is the entire file for reference -
Complete ExampleComponent.tsx -

- -```tsx -import React, { FC } from 'react'; -import { Typography, Grid } from '@material-ui/core'; -import { - InfoCard, - Header, - Page, - pageTheme, - Content, - ContentHeader, - HeaderLabel, - SupportButton, - identityApiRef, -} from '@backstage/core'; -import { useApi } from '@backstage/core-api'; -import ExampleFetchComponent from '../ExampleFetchComponent'; - -const ExampleComponent: FC<{}> = () => { - const identityApi = useApi(identityApiRef); - const userId = identityApi.getUserId(); - const profile = identityApi.getProfile(); - - return ( - -

- - -
- - - A description of your plugin goes here. - - - - - - {`${profile.displayName} | ${profile.email}`} - - - - - - - - - - ); -}; - -export default ExampleComponent; -``` - -

-
+ [ExampleComponent.tsx](https://github.com/spotify/backstage/tree/master/contrib/docs/tutorials/quickstart-app-plugin/ExampleComponent.md) # The Wipe @@ -188,7 +131,7 @@ changes, let's start by wiping this component clean. 1. Start by opening `root: plugins > github-playground > src > components > ExampleFetchComponent > ExampleFetchComponent.tsx` -1. Replace everyting in the file with the following: +1. Replace everything in the file with the following: ```tsx import React, { FC } from 'react'; @@ -329,8 +272,8 @@ const { value, loading, error } = useAsync(async (): Promise => { }, []); ``` -4. The resolved data is conventiently destructured with value containing our - Viewer type. loading as a boolean, self explainatory. And error which is +4. The resolved data is conveniently destructured with `value` containing our + Viewer type. `loading` as a boolean, self explanatory. And `error` which is present only if necessary. So let's use those as the first 3 of 4 multi return statements. 5. Add the _if return_ blocks below our async block @@ -358,123 +301,10 @@ return ( 8. After saving that, and given we don't have any errors, you should see a table with basic information on your repositories. 9. Here is the entire file for reference -
Complete ExampleFetchComponent.tsx -

- -```tsx -import React, { FC } from 'react'; -import { useAsync } from 'react-use'; -import Alert from '@material-ui/lab/Alert'; -import { - Table, - TableColumn, - Progress, - githubAuthApiRef, -} from '@backstage/core'; -import { useApi } from '@backstage/core-api'; -import { graphql } from '@octokit/graphql'; - -const query = `{ -viewer { - repositories(first: 100) { - totalCount - nodes { - name - createdAt - description - diskUsage - isFork - } - pageInfo { - endCursor - hasNextPage - } - } -} -}`; - -type Node = { - name: string; - createdAt: string; - description: string; - diskUsage: number; - isFork: boolean; -}; - -type Viewer = { - repositories: { - totalCount: number; - nodes: Node[]; - pageInfo: { - endCursor: string; - hasNextPage: boolean; - }; - }; -}; - -type DenseTableProps = { - viewer: Viewer; -}; - -export const DenseTable: FC = ({ viewer }) => { - const columns: TableColumn[] = [ - { title: 'Name', field: 'name' }, - { title: 'Created', field: 'createdAt' }, - { title: 'Description', field: 'description' }, - { title: 'Disk Usage', field: 'diskUsage' }, - { title: 'Fork', field: 'isFork' }, - ]; - - return ( -

- ); -}; - -const ExampleFetchComponent: FC<{}> = () => { - const auth = useApi(githubAuthApiRef); - - const { value, loading, error } = useAsync(async (): Promise => { - const token = await auth.getAccessToken(); - - const gqlEndpoint = graphql.defaults({ - // Uncomment baseUrl if using enterprise - // baseUrl: 'https://github.MY-BIZ.com/api', - headers: { - authorization: `token ${token}`, - }, - }); - const { viewer } = await gqlEndpoint(query); - return viewer; - }, []); - - if (loading) return ; - if (error) return {error.message}; - if (value && value.repositories) return ; - - return ( -
- ); -}; - -export default ExampleFetchComponent; -``` - -

- - -10. We finished! If there are no errors, you should see your own GitHub - repoistory information displayed in a basic table. If you run into issues, - you can compare the repo that backs this documdnt, + [ExampleFetchComponent.tsx](https://github.com/spotify/backstage/tree/master/contrib/docs/tutorials/quickstart-app-plugin/ExampleFetchComponent.md) +10. We finished! You should see your own GitHub repository's information + displayed in a basic table. If you run into issues, you can compare the repo + that backs this document, [simple-backstage-app-plugin](https://github.com/johnson-jesse/simple-backstage-app-plugin) # Where to go from here