From 3727322ecd4645431d62f6c261080f35d56f04a9 Mon Sep 17 00:00:00 2001 From: Eric Peterson Date: Wed, 14 Oct 2020 09:58:21 +0200 Subject: [PATCH] Clarify catalog info YAML, TechDocs (#2882) * Add note about catalog-info.yaml convention to format docs. * Improve TechDocs Create & Publish Docs: - Clarify the two paths to getting started - Clarify `catalog-info.yaml` / component registration - Minor grammar cleanup * Correct link to software catalog overview --- .../software-catalog/descriptor-format.md | 3 +++ .../techdocs/creating-and-publishing.md | 18 +++++++++++++----- 2 files changed, 16 insertions(+), 5 deletions(-) diff --git a/docs/features/software-catalog/descriptor-format.md b/docs/features/software-catalog/descriptor-format.md index 0c50e3669a..3a1db235a0 100644 --- a/docs/features/software-catalog/descriptor-format.md +++ b/docs/features/software-catalog/descriptor-format.md @@ -14,6 +14,9 @@ natively. In the API request/response cycle, a JSON representation is used, while the descriptor files are on YAML format to be more easily maintainable by humans. However, the structure and semantics is the same in both cases. +Although it's possible to name catalog entity descriptor files however you wish, +we recommend that you name them `catalog-info.yaml`. + ## Contents - [Overall Shape Of An Entity](#overall-shape-of-an-entity) diff --git a/docs/features/techdocs/creating-and-publishing.md b/docs/features/techdocs/creating-and-publishing.md index e1adedf25e..947e6de371 100644 --- a/docs/features/techdocs/creating-and-publishing.md +++ b/docs/features/techdocs/creating-and-publishing.md @@ -19,6 +19,12 @@ This section will guide you through: ## Create a basic documentation setup +If you have an existing repository that you'd like to add documentation to, skip +to the +[Manually add documentation setup](#manually-add-documentation-setup-to-already-existing-repository) +section below. Otherwise, continue reading to start a documentation repo from +scratch. + ### Use the documentation template Your working Backstage instance should by default have a documentation template @@ -35,9 +41,11 @@ setup for free. Prerequisities: -- `catalog-info.yml` file registered to Backstage. +- An existing component + [registered in backstage](../software-catalog/index.md#adding-components-to-the-catalog) + (e.g. via a `catalog-info.yaml` file). -Create a `mkdocs.yml` file in the root of the repository with the following +Create an `mkdocs.yml` file in the root of your repository with the following content: ```yaml @@ -50,8 +58,8 @@ plugins: - techdocs-core ``` -Update your `catalog-info.yaml` file in the root of the repository with the -following content: +Update your component's entity description by adding the following lines to its +`catalog-info.yaml` in the root of its repository: ```yaml metadata: @@ -59,7 +67,7 @@ metadata: backstage.io/techdocs-ref: dir:./ ``` -Create a `/docs` folder in the root of the project with at least a `index.md` +Create a `/docs` folder in the root of the project with at least an `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.)_