Merge pull request #257 from spotify/nikek/docs

Structure documentation in /docs

README.md

@@ -39,39 +39,9 @@ _\* not yet released_
 
 ![overview](backstage_overview.png)
 
-## Getting started
+## Documentation
 
-### Install Dependencies
-
-To run the frontend, you will need to have the following installed:
-
-- [git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)
-- [NodeJS](https://nodejs.org/en/download/) - Active LTS Release, currently v12
-- [yarn](https://classic.yarnpkg.com/en/docs/install)
-
-## Running the frontend locally
-
-Open a terminal window and start the web app using the following commands from the project root:
-
-```bash
-$ yarn # may take a while
-
-$ yarn start
-```
-
-The final `yarn start` command should open a local instance of Backstage in your browser, otherwise open one of the URLs printed in the terminal.
-
-## Plugins
-
-### Creating a Plugin
-
-To create a new plugin, make sure you're run `yarn` to install dependencies, then run the following:
-
-```bash
-$ yarn create-plugin
-```
-
-For more information see [Developing a Backstage Plugin](plugins/README.md).
+[Find the docs here.](docs/README.md)
 
 ## Developer support
 
@@ -80,10 +50,6 @@ Please join our [Discord](https://discordapp.com/) server:
 - [#general](https://discord.gg/MUpMjP2) - Developer focused discussions
 - [#support](https://discord.gg/dKhwsBp) - Support in how to use Backstage
 
-## Documentation
-
-_TODO: Add links to docs on backstage.io_
-
 ## License
 
 Copyright 2020 Spotify AB.

docs/README.md

@@ -0,0 +1,7 @@
+# Documentation
+
+Check out [https://backstage.io]() or see the table of content below.
+
+- [Architecture and terminology](architecture-terminology.md)
+- [Getting started](getting-started/README.md)
+- [References](reference/README.md)

docs/architecture-terminology.md

@@ -0,0 +1,9 @@
+# Architecture and Terminology
+
+Backstage is constructed out of three parts. We separate Backstage in this way because we see three groups of contributors to make an instance of Backstage a success.
+
+- Core - Base functionality - built by core devs in the open source project
+- App - The app is an instance of a Backstage app that is deployed and tweaked. The app ties together core functionality with additional plugins - built and maintained by app developers, usually a productivity team within a company.
+- Plugins - Additional functionality to make your Backstage app useful for your company. Plugins can be specific to a company or open sourced and reusable. At Spotify we have over 100 plugins built by over 50 different teams. It is very powerful to have contributions from various infrastructure teams into a single unified developer experience.
+
+[Back to Docs](README.md)

docs/getting-started/Plugin development.md

@@ -1,12 +1,13 @@
 # Plugin Development in Backstage
-Backstage plugins provide features to a Backstage App. 
 
-Each plugin is treated as a self-contained web app and can include almost any type of content. 
-Plugins all use a common set of platform APIs and reusable UI components. 
-Plugins can fetch data from external sources using the regular browser APIs or by depending on 
+Backstage plugins provide features to a Backstage App.
+
+Each plugin is treated as a self-contained web app and can include almost any type of content.
+Plugins all use a common set of platform APIs and reusable UI components.
+Plugins can fetch data from external sources using the regular browser APIs or by depending on
 external modules to do the work.
 
-## Creating a new plugin
+<!-- MOVED TO create-a-plugin.md ## Creating a new plugin
 On your command line, invoke the `backstage-cli` to create a new plugin:
 ```bash
 yarn create-plugin
@@ -14,25 +15,28 @@ yarn create-plugin
 
 ![](create-plugin_output.png)
 
-This will create a new Backstage Plugin based on the ID that was provided. It will be built and 
+This will create a new Backstage Plugin based on the ID that was provided. It will be built and
 added to the Backstage App automatically.
 
-*If `yarn start` is already running you should be able to see the default page for your new 
+*If `yarn start` is already running you should be able to see the default page for your new
 plugin directly by navigating to `http://localhost:3000/my-plugin`.*
 
-![](my-plugin_screenshot.png)
+![](my-plugin_screenshot.png) -->
 
 ## Developing guidelines
 
 - Consider writing plugins in `TypeScript`.
 - Plan the directory structure of your plugin so that it becomes easy to manage.
+- Prefer using the Backstage components, otherwise go with [Material-UI](https://material-ui.com/).
+- Check out the shared Backstage APIs before building a new one.
 
 ## Plugin concepts / API
 
 ### Routing
+
 Each plugin is responsible for registering its components to corresponding routes in the app.
 
-The app will call the `createPlugin` method on each plugin, passing in a `router` object with a set 
+The app will call the `createPlugin` method on each plugin, passing in a `router` object with a set
 of methods on it.
 
 ```typescript
@@ -48,6 +52,7 @@ export default createPlugin({
 ```
 
 #### `router` API
+
 ```typescript
 type RouterHooks = {
   registerRoute(

docs/getting-started/README.md

@@ -0,0 +1,11 @@
+# Getting started with Backstage
+
+Here is a collection of tutorials that will guide you through setting up and extending an instance of Backstage with your own plugins.
+
+- [Set up the environment](set-up-environment.md)
+- [Create/Run an instance of Backstage](create-run-an-instance.md)
+- [Create a Backstage plugin](create-a-plugin.md)
+- [Structure of a plugin](structure-of-a-plugin.md)
+- Using Backstage components (TODO)
+
+[Back to Docs](../README.md)

docs/getting-started/create-a-plugin.md

@@ -0,0 +1,21 @@
+# Create a plugin
+
+To create a new plugin, make sure you've run `yarn` and installed dependencies, then run the following on your command line (invoking the `backstage-cli`).
+
+```bash
+yarn create-plugin
+```
+
+![](create-plugin_output.png)
+
+This will create a new Backstage Plugin based on the ID that was provided. It will be built and
+added to the Backstage App automatically.
+
+_If `yarn start` is already running you should be able to see the default page for your new
+plugin directly by navigating to `http://localhost:3000/my-plugin`._
+
+![](my-plugin_screenshot.png)
+
+[Next Step - Structure of a plugin](structure-of-a-plugin.md)
+
+[Back to Getting Started](README.md)

docs/getting-started/create-run-an-instance.md

@@ -0,0 +1,15 @@
+# Run an instance of Backstage
+
+Open a terminal window and start the web app using the following commands from the project root:
+
+```bash
+$ yarn # may take a while
+
+$ yarn start
+```
+
+The final `yarn start` command should open a local instance of Backstage in your browser, otherwise open one of the URLs printed in the terminal.
+
+[Next step - Create a Backstage plugin](./create-a-plugin.md)
+
+[Back to Getting Started](README.md)

docs/getting-started/set-up-environment.md

@@ -0,0 +1,11 @@
+### Set up environment
+
+To run the frontend, you will need to have the following installed:
+
+- [git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)
+- [NodeJS](https://nodejs.org/en/download/) - Active LTS Release, currently v12
+- [yarn](https://classic.yarnpkg.com/en/docs/install)
+
+[Next step - Run an instance of the Backstage app](./create-run-an-instance.md)
+
+[Back to Getting Started](README.md)

docs/getting-started/structure-of-a-plugin.md

@@ -0,0 +1,76 @@
+# Structure of a newly created plugin
+
+Nice, you have a new plugin! We'll soon see how we can develop it into doing great things. But first off, let's look at what we get out of the box.
+
+## Folder structure
+
+The new plugin should look something like:
+
+```
+new-plugin/
+    dist/
+    node_modules/
+    src/
+        components/
+            ExampleComponent/
+                ExampleComponent.test.tsx
+                ExampleComponent.tsx
+                index.ts
+            ExampleFetchComponent/
+                ExampleFetchComponent.test.tsx
+                ExampleFetchComponent.tsx
+                index.ts
+        index.ts
+        plugin.test.ts
+        plugin.ts
+    jest.config.js
+    jest.setup.ts
+    package.json
+    README.md
+    tsconfig.json
+```
+
+You might note a thing or two. Yes, a plugin looks like a mini project on it's own with a `package.json` and a `src` folder. And this is because we want plugins to be separate packages. This makes it possible to ship plugins on npm and it lets you work on a plugin in isolation, without loading all the other plugins in a potentially big Backstage app.
+
+The `index.ts` files are there to let us import from the folder path and not specific files. It's a way to have control over the exports in one file per folder.
+
+## Base files
+
+In the root folder you have some configuration for typescript and jest, the test runner. You get a readme to populate with info about your plugin and a package.json to declare the plugin dependencies, metadata and scripts.
+
+## The plugin file
+
+In the `src` folder we get to the interesting bits. Check out the `plugin.ts`:
+
+```jsx
+import { createPlugin } from '@spotify-backstage/core';
+import ExampleComponent from './components/ExampleComponent';
+
+export default createPlugin({
+  id: 'new-plugin',
+  register({ router }) {
+    router.registerRoute('/new-plugin', ExampleComponent);
+  },
+});
+```
+
+This is where the plugin is created and where it hooks into the app by declaring what component should be shown on what url. See reference docs for [createPlugin(coming soon)](http://github.com/spotify/backstage/) or [router(coming soon)](http://github.com/spotify/backstage/).
+
+## Components
+
+The generated plugin includes two example components to showcase how we structure our plugins. There are usually one or multiple page components and next to them you can split up the UI in as many components as you feel like.
+
+We have the `ExamplePage` to show an example Backstage page component. The `ExampleFetchComponent` show cases the common task of making an async request to a public API and plot the response data in a table using Material-UI components.
+
+You may tweak these components, rename them and/or replace them completely.
+
+## Connecting the plugin to the Backstage app
+
+There are two things needed for a Backstage app to start making use of a plugin.
+
+1. Add plugin as dependency in `app/package.json`
+2. `import` plugin in `app/src/plugins.ts`
+
+Luckily these two steps happen automatically when you create a plugin with the Backstage CLI.
+
+[Back to Getting Started](README.md)

docs/reference/README.md

@@ -0,0 +1,8 @@
+# Reference documentation
+
+APIs and Components
+
+- [createPlugin](createPlugin.md)
+- [createPlugin - router](createPlugin-router.md)
+
+[Back to Docs](../README.md)

docs/reference/createPlugin-router.md

@@ -0,0 +1,21 @@
+# createPlugin - router
+
+The router that is passed to the `register` function includes makes it possible for plugins to hook into routing of the Backstage app and provide the end users with new views to navigate to.
+
+```typescript
+type RouterHooks = {
+  registerRoute(
+    path: RoutePath,
+    Component: ComponentType<any>,
+    options?: RouteOptions,
+  ): void;
+
+  registerRedirect(
+    path: RoutePath,
+    target: RoutePath,
+    options?: RouteOptions,
+  ): void;
+};
+```
+
+[Back to References](README.md)

docs/reference/createPlugin.md

@@ -0,0 +1,40 @@
+# createPlugin
+
+Taking a plugin config as argument and returns a new plugin.
+
+## Plugin Config
+
+```typescript
+function createPlugin(config: PluginConfig): BackstagePlugin;
+
+type PluginConfig = {
+  id: string;
+  register?(hooks: PluginHooks): void;
+};
+
+type PluginHooks = {
+  router: RouterHooks;
+};
+```
+
+[Read more about the router here](createPlugin-router.md)
+
+## Example Uses
+
+### Creating a basic plugin
+
+Showcasing adding multiple routes and a redirect.
+
+```jsx
+import { createPlugin } from '@spotify-backstage/core';
+import ExampleComponent from './components/ExampleComponent';
+
+export default createPlugin({
+  id: 'new-plugin',
+  register({ router }) {
+    router.registerRoute('/new-plugin', ExampleComponent);
+  },
+});
+```
+
+[Back to References](README.md)