paulononato/backstage
1
0
Fork 0
Code Issues Pull Requests Actions 23 Packages Projects Releases Wiki Activity

feat: more docs to backstage.io

Browse Source
This commit is contained in:
Ivan Shmidt
2020-08-12 12:06:14 +02:00
parent 4ef9628276
commit 0867d3dc30
50 changed files with 487 additions and 193 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/features/techdocs/FAQ.md
+7 -3
View File
@@ -1,8 +1,13 @@
# TechDocs FAQ
---
id: faqs
title: TechDocs FAQ
sidebar_label: FAQ
---
This page answers frequently asked questions about [TechDocs](README.md).
_Got a question that you think others might be interested in knowing the answer to? Edit this file
_Got a question that you think others might be interested in knowing the answer
to? Edit this file
[here](https://github.com/spotify/backstage/edit/master/docs/features/techdocs/FAQ.md)._
## Technology
@@ -25,4 +30,3 @@ package is a MkDocs Plugin that works like a wrapper around multiple MkDocs
plugins (e.g.
[MkDocs Monorepo Plugin](https://github.com/spotify/mkdocs-monorepo-plugin)) as
well as a selection of Python Markdown extensions that TechDocs supports.
docs/features/techdocs/README.md
+5 -1
View File
@@ -1,4 +1,8 @@
# TechDocs Documentation
---
id: techdocs-overview
title: TechDocs Documentation
sidebar_label: Overview
---
## What is it?
docs/features/techdocs/concepts.md
+6 -2
View File
@@ -1,6 +1,10 @@
# Concepts
---
id: concepts
title: Concepts
---
This page describes concepts that are introduced with Spotify's docs-like-code solution in Backstage.
This page describes concepts that are introduced with Spotify's docs-like-code
solution in Backstage.
### TechDocs Core Plugin
docs/features/techdocs/creating-and-publishing.md
+27 -14
View File
@@ -1,22 +1,29 @@
# Creating and publishing your docs
---
id: creating-and-publishing
title: Creating and publishing your docs
sidebar_label: Creating and Publishing Documentation
---
This section will guide you through:
- Creating a basic setup for your documentation
- Writing and previewing your documentation in a local Backstage environment
- Creating a build ready for publication
- Publishing your documentation and making your Backstage instance read your published docs.
- Publishing your documentation and making your Backstage instance read your
published docs.
## Prerequisities
- [Docker](https://docs.docker.com/get-docker/)
- Static file hosting
- A working Backstage instance with TechDocs installed
(see [TechDocs getting started](getting-started.md))
- A working Backstage instance with TechDocs installed (see
[TechDocs getting started](getting-started.md))
## Create a basic documentation setup
In your home directory (also known as `~`), create a directory that contains your documentation (for example, `hello-docs`). Inside this directory, create a file called `mkdocs.yml`. Below is a basic example of how it could look.
In your home directory (also known as `~`), create a directory that contains
your documentation (for example, `hello-docs`). Inside this directory, create a
file called `mkdocs.yml`. Below is a basic example of how it could look.
The `~/hello-docs/mkdocs.yml` file should have the following content:
@@ -65,15 +72,19 @@ You should now have a folder called `~/hello-docs/site/`.
## Deploy to a file server
In order to serve documentation to TechDocs, our Backstage plugin needs to download the HTML rendered from the previous step. This will likely exist on an external file server, or a storage solution such as Google Cloud Storage.
In order to serve documentation to TechDocs, our Backstage plugin needs to
download the HTML rendered from the previous step. This will likely exist on an
external file server, or a storage solution such as Google Cloud Storage.
When deploying documentation, it should be deployed on that file server/storage solution with the following convention: `{id}/{file}`. For example, if
you want to upload the `getting-started/index.html` file for the `backstage`
When deploying documentation, it should be deployed on that file server/storage
solution with the following convention: `{id}/{file}`. For example, if you want
to upload the `getting-started/index.html` file for the `backstage`
documentation site, we would upload it to our file server as
`backstage/getting-started/index.html`.
To explain further what this would look like for multiple documentation sites,
take a look at this example file tree that would be represented on your file server:
take a look at this example file tree that would be represented on your file
server:
```md
/backstage/index.html /backstage/getting-started/index.html
@@ -87,17 +98,19 @@ In this file tree, we have two documentation sites available: `backstage` and
on `http://example.com` as the server URL.
When you configure the TechDocs plugin in Backstage to use `http://example.com`
as the file server/storage solution, it will translate the following URLs to
the file server:
as the file server/storage solution, it will translate the following URLs to the
file server:
| Backstage URL | File Server URL |
| --------------------------------------------------------- | ------------------------------------------------------- |
| https://demo.backstage.io/docs/backstage/ | http://example.com/backstage/index.html |
| https://demo.backstage.io/docs/mkdocs/plugin-development/ | http://example.com/mkdocs/plugin-development/index.html |
Then deploying new sites is easy: simply copy over the `site/`
folder produced in the [Create documentation](#build-production-ready-documentation) step above to the file server/storage solution under the ID of the documentation site. It will then become immediately available in Backstage under
the same ID as you can see in the table above.
Then deploying new sites is easy: simply copy over the `site/` folder produced
in the [Create documentation](#build-production-ready-documentation) step above
to the file server/storage solution under the ID of the documentation site. It
will then become immediately available in Backstage under the same ID as you can
see in the table above.
So, if the URL to your file server is `http://example.com/`, your
`~/hello-docs/site` folder containing the documentation should be accessible at
docs/features/techdocs/getting-started.md
+21 -14
View File
@@ -1,17 +1,20 @@
# Getting Started
---
id: getting-started
title: Getting Started
---
> TechDocs is not yet feature complete - currently you can't set up a complete
> end-to-end working TechDocs plugin without customizing the plugin itself.
> What you can expect from TechDocs V.0 is a demonstration of how to integrate docs into
> Backstage. TechDocs can create docs using
> What you can expect from TechDocs V.0 is a demonstration of how to integrate
> docs into Backstage. TechDocs can create docs using
> [mkdocs](https://www.mkdocs.org/), as well as read published docs. If you
> publish generated docs and pass in a `storageUrl` in your `app-config.yaml`,
> you can view them in Backstage by going to
> `http://localhost:3000/docs/<remote-folder>`.
TechDocs functions as a plugin to
Backstage, so you will need to use Backstage to use TechDocs.
TechDocs functions as a plugin to Backstage, so you will need to use Backstage
to use TechDocs.
## What is Backstage?
@@ -38,17 +41,20 @@ To create a new Backstage application for TechDocs, run the following command:
npx @backstage/cli create-app
```
You will then be prompted to enter a name for your application. Once that's done, a new Backstage application will be created in a new folder. For
example, if you choose the name `hello-world`, a new `hello-world` folder is created containing your new Backstage application.
You will then be prompted to enter a name for your application. Once that's
done, a new Backstage application will be created in a new folder. For example,
if you choose the name `hello-world`, a new `hello-world` folder is created
containing your new Backstage application.
## Installing TechDocs
TechDocs is not provided with the Backstage application by default, so you will now need to set up TechDocs manually. It should take less
than a minute.
TechDocs is not provided with the Backstage application by default, so you will
now need to set up TechDocs manually. It should take less than a minute.
### Adding the package
The first step is to add the TechDocs plugin to your Backstage application. Navigate to your new Backstage application folder:
The first step is to add the TechDocs plugin to your Backstage application.
Navigate to your new Backstage application folder:
```bash
cd hello-world/
@@ -61,7 +67,7 @@ cd packages/app
yarn add @backstage/plugin-techdocs
```
After a short while, the TechDocs plugin should be successfully installed.
After a short while, the TechDocs plugin should be successfully installed.
Next, you need to set up some basic configuration. Enter the following command:
@@ -78,7 +84,8 @@ export { plugin as TechDocs } from '@backstage/plugin-techdocs';
### Setting the configuration
TechDocs allows for configuration of the docs storage URL through your
`app-config` file. The URL provided here is for demo docs to use for testing purposes.
`app-config` file. The URL provided here is for demo docs to use for testing
purposes.
To use the demo docs, add the following lines to `app-config.yaml`:
@@ -99,5 +106,5 @@ Open your browser at [http://localhost:3000/docs/](http://localhost:3000/docs/).
## Additional reading
* [Creating and publishing your docs](creating-and-publishing.md)
* [Back to README](README.md)
- [Creating and publishing your docs](creating-and-publishing.md)
- [Back to README](README.md)