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

Tweaks to techdocs docs

Browse Source 
Text editing
This commit is contained in:
Bodil Björklund
2020-07-30 17:04:03 +02:00
parent 86672eb8cc
commit 0fe2ddf70f
4 changed files with 58 additions and 77 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/features/techdocs/FAQ.md
+8 -9
View File
@@ -1,20 +1,23 @@
# TechDocs FAQ
This page answer frequently asked questions about [TechDocs].
This page answers frequently asked questions about [TechDocs](README.md).
#### Technology
_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
- [What static site generator is TechDocs using?](./#what-static-site-generator-is-techdocs-using)
- [What is the mkdocs-techdocs-core plugin?](./#what-is-the-mkdocs-techdocs-core-plugin)
## What static site generator is TechDocs using?
#### What static site generator is TechDocs using?
TechDocs is using [MkDocs](https://www.mkdocs.org/) to build project
doucmentation under the hood. Documentation built with the
documentation under the hood. Documentation built with the
[techdocs-container](https://github.com/spotify/backstage/blob/master/packages/techdocs-container/README.md)
is using the MkDocs Material Theme.
## What is the mkdocs-techdocs-core plugin?
#### What is the mkdocs-techdocs-core plugin?
The
[mkdocs-techdocs-core](https://github.com/spotify/backstage/blob/master/packages/techdocs-container/techdocs-core/README.md)
@@ -23,7 +26,3 @@ 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.
_Add a question that you think others might be interested in? Edit the file
[here](https://github.com/spotify/backstage/edit/master/docs/features/techdocs/FAQ.md)._
[techdocs]: README.md
docs/features/techdocs/concepts.md
+10 -11
View File
@@ -1,7 +1,6 @@
# Concepts
This page describes concepts that has been 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
@@ -20,34 +19,34 @@ MkDocs.
[TechDocs Container](../../../packages/techdocs-container/README.md)
### TechDocs publisher (Coming Soon)
### TechDocs publisher (coming soon)
### TechDocs CLI
The TechDocs CLI was created to make it easy to write, generate and preview
documentation for publishing. Currently it mostly acts as a wrapper around the
TechDocs container and provides a easy to use interface for our docker
TechDocs container and provides an easy-to-use interface for our docker
container.
[TechDocs CLI](../../../packages/techdocs-cli/README.md)
### TechDocs Reader
Documentation generated by TechDocs is generated as static html sites. The
TechDocs Reader was therefore created to be able to integrate pre-generated html
Documentation generated by TechDocs is generated as static HTML sites. The
TechDocs Reader was therefore created to be able to integrate pre-generated HTML
sites with the Backstage UI.
The TechDocs Reader purpose is also to open up the opportunity to integrate
TechDocs widgets for a customized full-featured TechDocs experience.
([Coming Soon V.2](https://github.com/spotify/backstage/milestone/17))
([coming soon V.2](https://github.com/spotify/backstage/milestone/17))
[TechDocs Reader](../../../plugins/techdocs/src/reader/README.md)
### Transformers
Transformers is different pieces of functionality used inside the TechDocs
Reader. The reason to why transformers were introduced is to provide a way to
transform the html content on pre and post render. (e.g. rewrite docs links or
modify css)
Transformers are different pieces of functionality used inside the TechDocs
Reader. The reason why transformers were introduced was to provide a way to
transform the HTML content on pre and post render (e.g. rewrite docs links or
modify css).
[Transformers API docs](../../../plugins/techdocs/src/reader/transformers/README.md)
docs/features/techdocs/creating-and-publishing.md
+14 -25
View File
@@ -5,22 +5,18 @@ 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 from
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
[TechDocs getting started](getting-started.md)
(see [TechDocs getting started](getting-started.md))
## Create a basic documentation setup
Create a directory that contains your documentation. Inside this directory you
should create a file called `mkdocs.yml`. As an example you can create a
directory called `hello-docs` in your home directory (also known as `~`). 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:
@@ -34,7 +30,7 @@ plugins:
- techdocs-core
```
And then the `~/hello-docs/docs/index.md` should have the following content:
The `~/hello-docs/docs/index.md` should have the following content:
```md
# example docs
@@ -58,7 +54,7 @@ npx techdocs-cli serve
## Build production ready documentation
To get a build suitable for publication you can build your docs using the
`spotify/techdocs` container.
`spotify/techdocs` container:
```bash
cd ~/hello-docs/
@@ -69,20 +65,15 @@ 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
[Create documentation](#create-documentation) step above. 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
we wanted 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 how this would look like for multiple documentation sites,
take a look at this example file tree that would be represented on your file
server:
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:
```md
/backstage/index.html /backstage/getting-started/index.html
@@ -96,7 +87,7 @@ 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
as the file server/storage solution, it will translate the following URLs to
the file server:
| Backstage URL | File Server URL |
@@ -104,10 +95,8 @@ the file server:
| 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. It's as simple as copying over the `site/`
folder produced in the [Create documentation](#create-documentation) step above
and copying it over to the file server / storage solution under the ID of the
documentation site. It will then become immediately available in Backstage under
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
@@ -120,7 +109,7 @@ In order for Backstage to show your documentation, it needs to know where you
uploaded it.
Make sure you have Backstage set up using
[TechDocs getting started](getting-started.md)
[TechDocs getting started](getting-started.md).
To point Backstage to your docs storage, add or change the following lines in
your Backstage `app-config.yaml`:
docs/features/techdocs/getting-started.md
+26 -32
View File
@@ -1,27 +1,27 @@
# Getting Started
> TechDocs is not feature complete and currently you can't set up a complete
> 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.
> With TechDocs V.0 you can expect a demonstration of how to integrate docs into
> Backstage. Currently it can create docs using
> [mkdocs](https://www.mkdocs.org/), as well as reading published docs. If you
> publish generated docs and passing in a storageUrl in your `app-config.yaml`
> you can view it in Backstage by going to
> 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>`.
Getting started with TechDocs is easy. TechDocs functions as a plugin to
Backstage, why 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?
Backstage is an open platform for building developer portals. It’s based on the
developer portal we’ve been using internally at Spotify for over four years.
[Read more](https://github.com/spotify/backstage).
[Read more here](https://github.com/spotify/backstage).
## Prerequisities
In order to use Backstage and TechDocs, you will need to have the following
In order to use Backstage and TechDocs, you need to have the following
installed:
- [Node.js](https://nodejs.org) Active LTS (long term support), currently v12
@@ -29,48 +29,41 @@ installed:
## Creating a new Backstage app
> If you have already created a Backstage application for this purpose, jump to
> If you have already created a Backstage application, jump to
> [Installing TechDocs](#installing-techdocs), otherwise complete this step.
To create a new Backstage application for us to set up TechDocs, you will need
to run the following command:
To create a new Backstage application for TechDocs, run the following command:
```bash
npx @backstage/cli create-app
```
You will then be prompted to enter a name for your application. Once you do so,
this will create a new Backstage application for you in a new folder. For
example, if we chose the name `hello-world` for our application, it would create
a new `hello-world` folder containing our 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
Inside of our new Backstage application, TechDocs is not provided by default.
For this reason we will need to manually set up TechDocs. It should take less
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
We will need to add our plugin to your Backstage application. To do so, you can
navigate to your new Backstage application folder and then run a single command
to install TechDocs.
The first step is to add the TechDocs plugin to your Backstage application. Navigate to your new Backstage application folder:
```bash
cd hello-world/
```
Then you need to navigate to your `packages/app` folder to install TechDocs:
Then navigate to your `packages/app` folder to install TechDocs:
```bash
cd packages/app
yarn add @backstage/plugin-techdocs
```
After a short while, it should successfully install the TechDocs plugin. Now we
just need to set up some basic configuration!
After a short while, the TechDocs plugin should be successfully installed.
Enter the following command:
Next, you need to set up some basic configuration. Enter the following command:
```bash
yarn install
@@ -85,7 +78,7 @@ 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 demo docs used to testing.
`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`:
@@ -94,16 +87,17 @@ techdocs:
storageUrl: https://techdocs-mock-sites.storage.googleapis.com
```
## Run Backstage Locally
## Run Backstage locally
Change folder to your Backstage application root.
Change folder to your Backstage application root and run the following command:
```bash
yarn start
```
Open browser at [http://localhost:3000/docs/](http://localhost:3000/docs/)
Open your browser at [http://localhost:3000/docs/](http://localhost:3000/docs/).
## Extra Reading
## Additional reading
[Back to Docs](README.md)
* [Creating and publishing your docs](creating-and-publishing.md)
* [Back to README](README.md)