From 0fe2ddf70fe68bd1850b1f2dfb7ac05913bb64e7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bodil=20Bj=C3=B6rklund?= Date: Thu, 30 Jul 2020 17:04:03 +0200 Subject: [PATCH] Tweaks to techdocs docs Text editing --- docs/features/techdocs/FAQ.md | 17 +++--- docs/features/techdocs/concepts.md | 21 ++++--- .../techdocs/creating-and-publishing.md | 39 +++++-------- docs/features/techdocs/getting-started.md | 58 +++++++++---------- 4 files changed, 58 insertions(+), 77 deletions(-) diff --git a/docs/features/techdocs/FAQ.md b/docs/features/techdocs/FAQ.md index ee9a40c983..f872e63718 100644 --- a/docs/features/techdocs/FAQ.md +++ b/docs/features/techdocs/FAQ.md @@ -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 diff --git a/docs/features/techdocs/concepts.md b/docs/features/techdocs/concepts.md index d0e3c3c0ea..f06ed8b4c0 100644 --- a/docs/features/techdocs/concepts.md +++ b/docs/features/techdocs/concepts.md @@ -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) diff --git a/docs/features/techdocs/creating-and-publishing.md b/docs/features/techdocs/creating-and-publishing.md index 0ac4f054d7..b38fb77b08 100644 --- a/docs/features/techdocs/creating-and-publishing.md +++ b/docs/features/techdocs/creating-and-publishing.md @@ -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`: diff --git a/docs/features/techdocs/getting-started.md b/docs/features/techdocs/getting-started.md index 2ea8fc7fa9..90dcd423fa 100644 --- a/docs/features/techdocs/getting-started.md +++ b/docs/features/techdocs/getting-started.md @@ -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/`. -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)