From f0f4997f96eab1cb53aef8e2429bdce4d2e74423 Mon Sep 17 00:00:00 2001 From: Eric Peterson Date: Wed, 28 Jul 2021 18:41:42 +0200 Subject: [PATCH] Document latest recommendations for techdocs-ref annotation Signed-off-by: Eric Peterson --- .../well-known-annotations.md | 14 ++-- .../techdocs/creating-and-publishing.md | 4 +- docs/features/techdocs/how-to-guides.md | 72 +++++++++++++------ 3 files changed, 60 insertions(+), 30 deletions(-) diff --git a/docs/features/software-catalog/well-known-annotations.md b/docs/features/software-catalog/well-known-annotations.md index 5f474624f9..c0c347ac17 100644 --- a/docs/features/software-catalog/well-known-annotations.md +++ b/docs/features/software-catalog/well-known-annotations.md @@ -63,12 +63,18 @@ the `app-config.yaml` of a Backstage installation. # Example: metadata: annotations: - backstage.io/techdocs-ref: url:https://github.com/backstage/backstage/tree/master + backstage.io/techdocs-ref: dir:. ``` -The value of this annotation is a location reference string (see above). If this -annotation is specified, it is expected to point to a repository that the -TechDocs system can read and generate docs from. +The value of this annotation informs _where_ TechDocs source content is stored +so that it can be read and docs can be generated from it. Most commonly, it's +written as a path, relative to the location of the `catalog-info.yaml` itself, +where the associated `mkdocs.yml` file can be found. + +In unusual situations where the documentation for a catalog entity does not live +alongside the entity's source code, the value of this annotation can point to an +absolute URL, matching the location reference string format outlined above, for +example: `url:https://github.com/backstage/backstage/tree/master` ### backstage.io/view-url, backstage.io/edit-url diff --git a/docs/features/techdocs/creating-and-publishing.md b/docs/features/techdocs/creating-and-publishing.md index 3fdc942ac4..93ce3ad4d9 100644 --- a/docs/features/techdocs/creating-and-publishing.md +++ b/docs/features/techdocs/creating-and-publishing.md @@ -66,9 +66,7 @@ Update your component's entity description by adding the following lines to its ```yaml metadata: annotations: - backstage.io/techdocs-ref: url:https://github.com/org/repo - # Or - # backstage.io/techdocs-ref: url:https://github.com/org/repo/tree/branchName/subFolder + backstage.io/techdocs-ref: dir:. ``` The diff --git a/docs/features/techdocs/how-to-guides.md b/docs/features/techdocs/how-to-guides.md index 3f3c92d0de..e1533498d7 100644 --- a/docs/features/techdocs/how-to-guides.md +++ b/docs/features/techdocs/how-to-guides.md @@ -35,38 +35,64 @@ In your Backstage instance's `app-config.yaml`, set `techdocs.builder` from `'local'` to `'external'`. By doing this, TechDocs will not try to generate docs. Look at [TechDocs configuration](configuration.md) for reference. -## How to use URL Reader in TechDocs Prepare step? +## How to understand techdocs-ref annotation values -If TechDocs is configured to generate docs, it will first download the -repository associated with the `backstage.io/techdocs-ref` annotation defined in -the Entity's `catalog-info.yaml` file. This is also called the +If TechDocs is configured to generate docs, it will first download source files +based on the value of the `backstage.io/techdocs-ref` annotation defined in the +Entity's `catalog-info.yaml` file. This is also called the [Prepare](./concepts.md#techdocs-preparer) step. -There are two kinds of preparers or two ways of downloading these source files +We strongly recommend that the `backstage.io/techdocs-ref` annotation in each +documented catalog entity's `catalog-info.yaml` be set to `dir:.` in almost all +situations. This is because TechDocs is aligned with the "docs like code" +philosophy, whereby documentation should be authored and managed alongside the +source code of the underlying software itself. -- Preparer 1: Doing a `git clone` of the repository (also known as Common Git - Preparer) -- Preparer 2: Downloading an archive.zip or equivalent of the repository (also - known as URL Reader) +When you see `dir:.`, you can translate it to mean: -If `backstage.io/techdocs-ref` is equal to any of these - +- That the documentation source code lives in the same location as the + `catalog-info.yaml` file. +- That, in particular, the `mkdocs.yml` file is a sibling of `catalog-info.yaml` + (meaning, it is in the same directory) +- And that all of the source content of the documentation would be available if + one were to download the directory containing those two files (as well as all + sub-directories). -1. `github:https://githubhost.com/org/repo` -2. `gitlab:https://gitlabhost.com/org/repo` -3. `bitbucket:https://bitbuckethost.com/project/repo` -4. `azure/api:https://azurehost.com/org/project` +The directory tree of the entity would look something like this: -Then Common Git Preparer will be used i.e. a `git clone`. But the URL Reader is -a much faster way to do this step. Convert the `backstage.io/techdocs-ref` -values to the following - +``` +├── catalog-info.yaml +├── mkdocs.yml +└── docs + └── index.md +``` -1. `url:https://githubhost.com/org/repo/tree/` -2. `url:https://gitlabhost.com/org/repo/tree/` -3. `url:https://bitbuckethost.com/project/repo/src/` -4. `url:https://azurehost.com/organization/project/_git/repository` +If, for example, you wanted to keep a lean root directory, you could place your +`mkdocs.yml` file in a subdirectory and update the `backstage.io/techdocs-ref` +annotation value accordingly, e.g. to `dir:./sub-folder`: -Note that you can also provide a path to a non-root directory inside the -repository which contains the `docs/` directory. +``` +├── catalog-info.yaml +└── sub-folder + ├── mkdocs.yml + └── docs + └── index.md +``` + +In rare situations where your TechDocs source content is managed and stored in a +location completely separate from your `catalog-info.yaml`, you can instead +specify a URL location reference, the exact value of which will vary based on +the source code hosting provider. Notice that instead of the `dir:` prefix, the +`url:` prefix is used instead. For example: + +- **GitHub**: `url:https://githubhost.com/org/repo/tree/` +- **GitLab**: `url:https://gitlabhost.com/org/repo/tree/` +- **Bitbucket**: `url:https://bitbuckethost.com/project/repo/src/` +- **Azure**: `url:https://azurehost.com/organization/project/_git/repository` + +Note, just as it's possible to specify a subdirectory with the `dir:` prefix, +you can also provide a path to a non-root directory inside the repository which +contains the `mkdocs.yml` file and `docs/` directory. e.g. `url:https://github.com/backstage/backstage/tree/master/plugins/techdocs-backend/examples/documented-component`