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

TechDocs: update techdocs docs (#2105)

Browse Source 
* docs(techdocs): update getting started docs

* docs(techdocs): update text and link to version

* fix docs link

* fix docs link

* Update docs/features/techdocs/getting-started.md

* update creating and publishing docs
This commit is contained in:
Emma Indal
2020-08-25 16:43:14 +02:00
committed by GitHub
parent f6826d9107
commit 40de8e03d4
5 changed files with 60 additions and 113 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/features/techdocs/concepts.md
+1 -1
View File
@@ -42,7 +42,7 @@ 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.3](./README.md#project-roadmap))
[TechDocs Reader](https://github.com/spotify/backstage/blob/master/plugins/techdocs/src/reader/README.md)
docs/features/techdocs/creating-and-publishing.md
+41 -90
View File
@@ -6,26 +6,38 @@ 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.
- [Create a basic documentation setup](#create-a-basic-documentation-setup)
- [Use the documentation template](#use-the-documentation-template)
- [Manually add documentation setup to already existing repository](#manually-add-documentation-setup-to-already-existing-repository)
- [Writing and previewing your documentation](#writing-and-previewing-your-documentation)
## 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))
## 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.
### Use the documentation template
The `~/hello-docs/mkdocs.yml` file should have the following content:
Your working Backstage instance should by default have a documentation template
added. If not, follow these
[instructions](../software-templates/installation.md#adding-templates) to add
the documentation template.
![Documentation Template](../../assets/techdocs/documentation-template.png)
Create an entity from the documentation template and you will get the needed
setup for free.
### Manually add documentation setup to already existing repository
Prerequisities:
- `catalog-info.yml` file registered to Backstage.
Create a `mkdocs.yml` file in the root of the repository with the following
content:
```yaml
site_name: 'example-docs'
@@ -37,7 +49,20 @@ plugins:
- techdocs-core
```
The `~/hello-docs/docs/index.md` should have the following content:
Update your `catalog-info.yaml` file in the root of the repository with the
following content:
```yaml
metadata:
annotations:
backstage.io/techdocs-ref: dir:./
```
Create a `/docs` folder in the root of the project with at least a `index.md`
file. _(If you add more markdown files, make sure to update the nav in the
mkdocs.yml file to get a proper navigation for your documentation.)_
The `docs/index.md` can for example have the following content:
```md
# example docs
@@ -45,6 +70,9 @@ The `~/hello-docs/docs/index.md` should have the following content:
This is a basic example of documentation.
```
Commit your changes, open a pull request and merge. You will now get your
updated documentation next time you run Backstage!
## Writing and previewing your documentation
Using the `techdocs-cli` you can preview your docs inside a local Backstage
@@ -54,83 +82,6 @@ want to write your documentation.
To do this you can run:
```bash
cd ~/hello-docs/
cd ~/<repository-path>/
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:
```bash
cd ~/hello-docs/
docker run -it -w /content -v $(pwd):/content spotify/techdocs build
```
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.
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:
```md
/backstage/index.html /backstage/getting-started/index.html
/backstage/contributing/index.html /mkdocs/index.html
/mkdocs/plugin-development/index.html
/mkdocs/plugin-development/debugging/index.html
```
In this file tree, we have two documentation sites available: `backstage` and
`mkdocs`. Each of them expose several pages. Let's say both of these are hosted
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:
| 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.
So, if the URL to your file server is `http://example.com/`, your
`~/hello-docs/site` folder containing the documentation should be accessible at
`http://example.com/hello-docs/`.
## Configure TechDocs to read from file server
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).
To point Backstage to your docs storage, add or change the following lines in
your Backstage `app-config.yaml`:
```yaml
techdocs:
storageUrl: http://example.com
```
You can now start Backstage using `yarn start` and open up your browser at
`http://localhost:3000/docs/hello-docs` to view your docs.
docs/features/techdocs/getting-started.md
+17 -17
View File
@@ -3,16 +3,6 @@ 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
> [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.
@@ -48,8 +38,8 @@ 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 provided with the Backstage application by default. If you want to
set up TechDocs manually, keep follow the instructions below.
### Adding the package
@@ -84,19 +74,29 @@ 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.
To use the demo docs, add the following lines to `app-config.yaml`:
The default storage URL:
```yaml
techdocs:
storageUrl: https://techdocs-mock-sites.storage.googleapis.com
storageUrl: http://localhost:7000/techdocs/static/docs
```
If you want to configure this to point to another storage URL, change the value
of `storageUrl`.
## Run Backstage locally
Change folder to your Backstage application root and run the following command:
Change folder to `<backstage-project-root>/packages/backend` and run the
following command:
```bash
yarn start
```
Open a new command line window. Change directory to your Backstage application
root and run the following command:
```bash
yarn start