From a6b33a0faf8cde31cf8f227febad18aa17ad7e63 Mon Sep 17 00:00:00 2001 From: Emma Indal Date: Tue, 21 Jul 2020 11:00:35 +0200 Subject: [PATCH 1/3] wip --- docs/features/techdocs/concepts.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/docs/features/techdocs/concepts.md b/docs/features/techdocs/concepts.md index 74d42e13cd..e237e4b10b 100644 --- a/docs/features/techdocs/concepts.md +++ b/docs/features/techdocs/concepts.md @@ -1 +1,13 @@ # Concepts + +This page describes concepts that has been introduced with Spotify's +docs-like-code solution in Backstage. + +### Transformers + +Transformers is an abstraction of functionality that are responsible for +different things. The reason to why transformers were introduced is to provide a +others to be able to switch out transformers as it fits your TechDocs solution. + +Interested in how transformers work? +[Read more here.](../../../plugins/techdocs/src/reader/transformers/README.md) From 4f5ed073f327c41eefd982cff27c5f76f572a35e Mon Sep 17 00:00:00 2001 From: Emma Indal Date: Tue, 21 Jul 2020 15:02:36 +0200 Subject: [PATCH 2/3] fix(techdocs-docs-concepts): TechDocs concept documentation --- docs/features/techdocs/concepts.md | 49 +++++++++++++++++++++++++++--- 1 file changed, 44 insertions(+), 5 deletions(-) diff --git a/docs/features/techdocs/concepts.md b/docs/features/techdocs/concepts.md index e237e4b10b..e758890640 100644 --- a/docs/features/techdocs/concepts.md +++ b/docs/features/techdocs/concepts.md @@ -3,11 +3,50 @@ This page describes concepts that has been introduced with Spotify's docs-like-code solution in Backstage. +### TechDocs Core Plugin + +The TechDocs Core Plugin is a MkDocs plugin created as a wrapper around multiple +MkDocs plugins and Python Markdown extensions to standardize the configuration +of MkDocs used for TechDocs. + +[TechDocs Core](../../../packages/techdocs-container/techdocs-core/README.md) + +### TechDocs container + +The TechDocs container is a Docker container that builds the HTML documentation +pages from Python flavoured markdown through MkDocs, including e.g. buttons +(more here) and styles. + +[TechDocs Container](../../../packages/techdocs-container/README.md) + +### TechDocs publisher (Coming Soon) + +### TechDocs CLI + +The TechDocs CLI was created to make it easy to write, generate and preview +documentation for publishing. Currently it mostly acts as a wrapper around the +TechDocs container and provides a easy to use interface for our docker +container. + +[TechDocs CLI](../../../packages/techdocs-cli/README.md) + +### TechDocs Reader + +Documentation generated by TechDocs is generated as static html sites. The +TechDocs Reader was therefore created to be able to integrate pre-generated html +sites with the Backstage UI. + +The TechDocs Reader purpose is also to open up the opportunity to integrate +TechDocs widgets for a customized full-featured TechDocs experience. +([Coming Soon V.2](https://github.com/spotify/backstage/milestone/17)) + +[TechDocs Reader](../../../plugins/techdocs/src/reader/README.md) + ### Transformers -Transformers is an abstraction of functionality that are responsible for -different things. The reason to why transformers were introduced is to provide a -others to be able to switch out transformers as it fits your TechDocs solution. +Transformers is different pieces of functionality used inside the TechDocs +Reader. The reason to why transformers were introduced is to provide a way to +transform the html content on pre and post render. (e.g. rewrite docs links or +modify css) -Interested in how transformers work? -[Read more here.](../../../plugins/techdocs/src/reader/transformers/README.md) +[Transformers API docs](../../../plugins/techdocs/src/reader/transformers/README.md) From 6404144d1307e37e4a3a8e1e44b1070e5192dbf1 Mon Sep 17 00:00:00 2001 From: ellinors Date: Tue, 21 Jul 2020 17:02:22 +0200 Subject: [PATCH 3/3] fix(techdocs): updated concepts documentation. --- docs/features/techdocs/concepts.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/features/techdocs/concepts.md b/docs/features/techdocs/concepts.md index e758890640..d0e3c3c0ea 100644 --- a/docs/features/techdocs/concepts.md +++ b/docs/features/techdocs/concepts.md @@ -13,9 +13,10 @@ of MkDocs used for TechDocs. ### TechDocs container -The TechDocs container is a Docker container that builds the HTML documentation -pages from Python flavoured markdown through MkDocs, including e.g. buttons -(more here) and styles. +The TechDocs container is a Docker container available at +[DockerHub](https://hub.docker.com/r/spotify/techdocs). It builds static HTML +pages, including stylesheets and scripts from Python flavored Markdown, through +MkDocs. [TechDocs Container](../../../packages/techdocs-container/README.md)