diff --git a/docs/assets/techdocs/documentation-template.png b/docs/assets/techdocs/documentation-template.png new file mode 100644 index 0000000000..1f44ad27c6 Binary files /dev/null and b/docs/assets/techdocs/documentation-template.png differ diff --git a/docs/features/techdocs/concepts.md b/docs/features/techdocs/concepts.md index fd87543994..7d5b5325cf 100644 --- a/docs/features/techdocs/concepts.md +++ b/docs/features/techdocs/concepts.md @@ -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) diff --git a/docs/features/techdocs/creating-and-publishing.md b/docs/features/techdocs/creating-and-publishing.md index 342b846dcc..abb56b348a 100644 --- a/docs/features/techdocs/creating-and-publishing.md +++ b/docs/features/techdocs/creating-and-publishing.md @@ -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 ~// 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. diff --git a/docs/features/techdocs/getting-started.md b/docs/features/techdocs/getting-started.md index 094f9a8378..414b3baae8 100644 --- a/docs/features/techdocs/getting-started.md +++ b/docs/features/techdocs/getting-started.md @@ -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/`. - 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 `/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 diff --git a/mkdocs.yml b/mkdocs.yml index e227ab8f9d..74f9815483 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -42,11 +42,7 @@ nav: - Overview: 'features/techdocs/README.md' - Getting Started: 'features/techdocs/getting-started.md' - Concepts: 'features/techdocs/concepts.md' - - Reading Documentation: 'features/techdocs/reading-documentation.md' - - Writing Documentation: 'features/techdocs/writing-documentation.md' - - Publishing Documentation: 'features/techdocs/publishing-documentation.md' - - Contributing: 'features/techdocs/contributing.md' - - Debugging: 'features/techdocs/debugging.md' + - Creating and Publishing Documentation: 'features/techdocs/creating-and-publishing.md' - FAQ: 'features/techdocs/FAQ.md' - Plugins: - Overview: 'plugins/index.md'