TechDocs: Use a flag to determine if we should use a local mkdocs or techdocs-container (#2503)

* Use a flag to determine wether to use techdocs-container or local install of mkdocs

* Updated techdocs generator to look at app-config string instead of argument to decide how to run the generator

* Removed console log...

* Reverted scaffolder file that was accidentally committed.

* Fixed lint issues

* Added config to create-app template
This commit is contained in:
Sebastian Qvarfordt
2020-09-18 14:02:35 +02:00
committed by GitHub
parent ddc1cbd96a
commit f097c32b59
8 changed files with 97 additions and 30 deletions
+24
View File
@@ -71,6 +71,30 @@ building and publishing of your documentation, you want to change the
`requestUrl` to point to your storage. In this case `storageUrl` is not
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.
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
`local` mkdocs or run it from `docker`. This defaults to running as `docker` if
no config is provided.
```yaml
techdocs:
generators:
techdocs: local
```
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.
## Run Backstage locally
Change folder to `<backstage-project-root>/packages/backend` and run the