From efff67c205aed75997a1badca2e91385f236e662 Mon Sep 17 00:00:00 2001 From: Himanshu Mishra Date: Fri, 30 Oct 2020 09:49:53 +0100 Subject: [PATCH 1/2] TechDocs: Update docs around docker-in-docker installation Fix python package name to mkdocs-techdocs-core Refer to the original Dockerfile where users can seek inspiration from --- docs/features/techdocs/getting-started.md | 22 ++++++++++++++-------- 1 file changed, 14 insertions(+), 8 deletions(-) diff --git a/docs/features/techdocs/getting-started.md b/docs/features/techdocs/getting-started.md index 72efb6eee0..288ddb74ae 100644 --- a/docs/features/techdocs/getting-started.md +++ b/docs/features/techdocs/getting-started.md @@ -73,10 +73,10 @@ required. ### Disable Docker in Docker situation (Optional) -The TechDocs backend plugin runs a docker container with mkdocs to generate the -frontend of the docs from source files (Markdown). If you are deploying -Backstage using Docker, this will mean that your Backstage Docker container will -try to run another Docker container for TechDocs backend. +The TechDocs backend plugin runs a docker container with mkdocs installed to +generate the frontend of the docs from source files (Markdown). If you are +deploying Backstage using Docker, this will mean that your Backstage Docker +container will try to run another Docker container for TechDocs backend. To avoid this problem, we have a configuration available. You can set a value in your `app-config.yaml` that tells the techdocs generator if it should run the @@ -90,10 +90,16 @@ techdocs: ``` Setting `generators.techdocs` to `local` means you will have to make sure your -environment is compatible with techdocs. You will have to install the -`mkdocs-techdocs-container` and 'mkdocs' package from pip, as well as graphviz -and plantuml from your package manager. This has only been tested with python -3.7 and python 3.8. +environment is compatible with techdocs. + +You will have to install the `mkdocs-techdocs-core` and `mkdocs` package from +pip, as well as `graphviz` and `plantuml` from your OS package manager (e.g. +apt). See our +[Dockerfile](https://github.com/spotify/backstage/blob/master/packages/techdocs-container/Dockerfile) +for the latest requirements. You should be trying to match your Dockerfile with +this one. + +It is worth mentioning that we recommend Python version 3.7 or higher. ## Run Backstage locally From 6018855f34e1d1cb19bf904285ed52984243d1cb Mon Sep 17 00:00:00 2001 From: Himanshu Mishra Date: Fri, 30 Oct 2020 10:28:31 +0100 Subject: [PATCH 2/2] TechDocs: Add caveat around Markdown version --- docs/features/techdocs/getting-started.md | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-) diff --git a/docs/features/techdocs/getting-started.md b/docs/features/techdocs/getting-started.md index 288ddb74ae..cbbbc1e6cd 100644 --- a/docs/features/techdocs/getting-started.md +++ b/docs/features/techdocs/getting-started.md @@ -92,14 +92,21 @@ techdocs: Setting `generators.techdocs` to `local` means you will have to make sure your environment is compatible with techdocs. -You will have to install the `mkdocs-techdocs-core` and `mkdocs` package from +You will have to install the `mkdocs` and `mkdocs-techdocs-core` package from pip, as well as `graphviz` and `plantuml` from your OS package manager (e.g. apt). See our [Dockerfile](https://github.com/spotify/backstage/blob/master/packages/techdocs-container/Dockerfile) for the latest requirements. You should be trying to match your Dockerfile with this one. -It is worth mentioning that we recommend Python version 3.7 or higher. +Note: We recommend Python version 3.7 or higher. + +Caveat: Please install the `mkdocs-techdocs-core` package after all other Python +packages. The order is important to make sure we get correct version of some of +the dependencies. For example, we want `Markdown` version to be +[3.2.2](https://github.com/spotify/backstage/blob/f9f70c225548017b6a14daea75b00fbd399c11eb/packages/techdocs-container/techdocs-core/requirements.txt#L11). +You can also explicitly install `Markdown==3.2.2` after installing all other +Python packages. ## Run Backstage locally