From e4b4740095ac67fc775d6b57c4c01f1ad42f67db Mon Sep 17 00:00:00 2001 From: Adam Harvey Date: Thu, 14 Jan 2021 22:23:15 -0500 Subject: [PATCH 1/3] Add changeset --- .changeset/spotty-moons-tap.md | 5 +++++ 1 file changed, 5 insertions(+) create mode 100644 .changeset/spotty-moons-tap.md diff --git a/.changeset/spotty-moons-tap.md b/.changeset/spotty-moons-tap.md new file mode 100644 index 0000000000..facb76a296 --- /dev/null +++ b/.changeset/spotty-moons-tap.md @@ -0,0 +1,5 @@ +--- +'@backstage/plugin-catalog-backend': patch +--- + +Reduce log noise on locations refresh From 177f7984d870cafeeff4f3e40206ba5e5761f2c0 Mon Sep 17 00:00:00 2001 From: Adam Harvey Date: Fri, 15 Jan 2021 14:10:09 -0500 Subject: [PATCH 2/3] Add TechDocs CLI for mkdocs build errors --- docs/features/techdocs/troubleshooting.md | 50 +++++++++++++++++++++-- 1 file changed, 47 insertions(+), 3 deletions(-) diff --git a/docs/features/techdocs/troubleshooting.md b/docs/features/techdocs/troubleshooting.md index 3a9b2fcfd0..f2dc65704a 100644 --- a/docs/features/techdocs/troubleshooting.md +++ b/docs/features/techdocs/troubleshooting.md @@ -5,6 +5,50 @@ sidebar_label: Troubleshooting description: Troubleshooting for TechDocs --- -- TechDocs will fail to clone your docs if you have a git config which overrides - the `https` protocol with `ssh` or something else. Make sure to remove your - git config locally when you try TechDocs. +## Failure to clone + +TechDocs will fail to clone your docs if you have a git config which overrides +the `https` protocol with `ssh` or something else. Make sure to remove your git +config locally when you try TechDocs. + +## MkDocs Build Errors + +Using the [TechDocs CLI](https://github.com/backstage/techdocs-cli), you can +troubleshoot MkDocs build issues locally. Note this requires you have Docker +available to launch images. First, `git clone` the target repository locally, +then in the root of the repository, run: + +``` +npx @techdocs/cli serve +``` + +For example, if you have forgotten to put an MkDocs configuration file in your +repo, the resulting error will be: + +``` +npx: installed 278 in 9.089s +[techdocs-preview-bundle] Running local version of Backstage at http://localhost:3000 +INFO - Building documentation... + +Config file '/content/mkdocs.yml' does not exist. +``` + +When it works, a local copy of both Backstage and your site will be launched +locally: + +``` +npx: installed 278 in 9.682s +[techdocs-preview-bundle] Running local version of Backstage at http://localhost:3000 +INFO - Building documentation... +WARNING - Config value: 'dev_addr'. Warning: The use of the IP address '0.0.0.0' suggests a production environment or the use of a proxy to connect to the MkDocs server. However, the MkDocs' server is intended for local development purposes only. Please use a third party production-ready server instead. +INFO - Cleaning site directory +DEBUG - Successfully imported extension module "plantuml_markdown". +DEBUG - Successfully loaded extension "plantuml_markdown.PlantUMLMarkdownExtension". +INFO - Documentation built in 0.23 seconds +[I 210115 19:00:45 server:335] Serving on http://0.0.0.0:8000 +INFO - Serving on http://0.0.0.0:8000 +[I 210115 19:00:45 handlers:62] Start watching changes +INFO - Start watching changes +[I 210115 19:00:45 handlers:64] Start detecting changes +INFO - Start detecting changes +``` From 33f7fbc5b20c8514eab2931555b125cebba8bd29 Mon Sep 17 00:00:00 2001 From: Adam Harvey Date: Fri, 15 Jan 2021 14:12:23 -0500 Subject: [PATCH 3/3] Fix wrapping --- docs/features/techdocs/troubleshooting.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/docs/features/techdocs/troubleshooting.md b/docs/features/techdocs/troubleshooting.md index f2dc65704a..e6efefc578 100644 --- a/docs/features/techdocs/troubleshooting.md +++ b/docs/features/techdocs/troubleshooting.md @@ -40,7 +40,10 @@ locally: npx: installed 278 in 9.682s [techdocs-preview-bundle] Running local version of Backstage at http://localhost:3000 INFO - Building documentation... -WARNING - Config value: 'dev_addr'. Warning: The use of the IP address '0.0.0.0' suggests a production environment or the use of a proxy to connect to the MkDocs server. However, the MkDocs' server is intended for local development purposes only. Please use a third party production-ready server instead. +WARNING - Config value: 'dev_addr'. Warning: The use of the IP address '0.0.0.0' + suggests a production environment or the use of a proxy to connect to the MkDocs + server. However, the MkDocs' server is intended for local development purposes only. + Please use a third party production-ready server instead. INFO - Cleaning site directory DEBUG - Successfully imported extension module "plantuml_markdown". DEBUG - Successfully loaded extension "plantuml_markdown.PlantUMLMarkdownExtension".