From ebdfadc3f9e8ace72fd9d004e6ceb97ef365ca17 Mon Sep 17 00:00:00 2001 From: ellinors Date: Wed, 22 Jul 2020 11:51:42 +0200 Subject: [PATCH 1/3] fix(techdocs): remove unused doc files and merge some docs into one file --- docs/features/techdocs/README.md | 2 +- docs/features/techdocs/contributing.md | 1 - ...entation.md => creating-and-publishing.md} | 32 +++++++++++++++++-- docs/features/techdocs/debugging.md | 1 - .../techdocs/reading-documentation.md | 1 - .../techdocs/writing-documentation.md | 1 - 6 files changed, 30 insertions(+), 8 deletions(-) delete mode 100644 docs/features/techdocs/contributing.md rename docs/features/techdocs/{publishing-documentation.md => creating-and-publishing.md} (80%) delete mode 100644 docs/features/techdocs/debugging.md delete mode 100644 docs/features/techdocs/reading-documentation.md delete mode 100644 docs/features/techdocs/writing-documentation.md diff --git a/docs/features/techdocs/README.md b/docs/features/techdocs/README.md index d5d6db1240..7377a9123a 100644 --- a/docs/features/techdocs/README.md +++ b/docs/features/techdocs/README.md @@ -56,7 +56,7 @@ Spotify’s developer experience offering with 2,400+ documentation sites and [concepts]: concepts.md [reading documentation]: reading-documentation.md [writing documentation]: writing-documentation.md -[publishing documentation]: publishing-documentation.md +[publishing documentation]: writing-and-publishing.md [contributing]: contributing.md [debugging]: debugging.md [faq]: FAQ.md 'Frequently asked questions' diff --git a/docs/features/techdocs/contributing.md b/docs/features/techdocs/contributing.md deleted file mode 100644 index 854139a319..0000000000 --- a/docs/features/techdocs/contributing.md +++ /dev/null @@ -1 +0,0 @@ -# Contributing diff --git a/docs/features/techdocs/publishing-documentation.md b/docs/features/techdocs/creating-and-publishing.md similarity index 80% rename from docs/features/techdocs/publishing-documentation.md rename to docs/features/techdocs/creating-and-publishing.md index 73ac74b458..0ac4f054d7 100644 --- a/docs/features/techdocs/publishing-documentation.md +++ b/docs/features/techdocs/creating-and-publishing.md @@ -1,11 +1,21 @@ -# Publishing Documentation +# Creating and publishing your docs + +This section will guide you through: + +- Creating a basic setup for your documentation +- Writing and previewing your documentation in a local Backstage environment +- Creating a build ready for publication +- Publishing your documentation and making your Backstage instance read from + your published docs. ## Prerequisities - [Docker](https://docs.docker.com/get-docker/) - Static file hosting +- A working Backstage instance with TechDocs installed + [TechDocs getting started](getting-started.md) -## Create documentation +## Create a basic documentation setup Create a directory that contains your documentation. Inside this directory you should create a file called `mkdocs.yml`. As an example you can create a @@ -32,7 +42,23 @@ And then the `~/hello-docs/docs/index.md` should have the following content: This is a basic example of documentation. ``` -## Build documentation +## Writing and previewing your documentation + +Using the `techdocs-cli` you can preview your docs inside a local Backstage +instance and get automatic recompilation on changes. This is useful for when you +want to write your documentation. + +To do this you can run: + +```bash +cd ~/hello-docs/ +npx techdocs-cli serve +``` + +## Build production ready documentation + +To get a build suitable for publication you can build your docs using the +`spotify/techdocs` container. ```bash cd ~/hello-docs/ diff --git a/docs/features/techdocs/debugging.md b/docs/features/techdocs/debugging.md deleted file mode 100644 index 1e584c954d..0000000000 --- a/docs/features/techdocs/debugging.md +++ /dev/null @@ -1 +0,0 @@ -# Debugging diff --git a/docs/features/techdocs/reading-documentation.md b/docs/features/techdocs/reading-documentation.md deleted file mode 100644 index f872ed5df8..0000000000 --- a/docs/features/techdocs/reading-documentation.md +++ /dev/null @@ -1 +0,0 @@ -# Reading Documentation diff --git a/docs/features/techdocs/writing-documentation.md b/docs/features/techdocs/writing-documentation.md deleted file mode 100644 index 5fea01bcad..0000000000 --- a/docs/features/techdocs/writing-documentation.md +++ /dev/null @@ -1 +0,0 @@ -# Writing Documentation From 12f4979cdfb1fe19b582deabfb7a88f199e9ddd3 Mon Sep 17 00:00:00 2001 From: ellinors Date: Wed, 22 Jul 2020 11:53:06 +0200 Subject: [PATCH 2/3] fix(techdocs): updated link in techdocs README.md to point to new file --- docs/features/techdocs/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/features/techdocs/README.md b/docs/features/techdocs/README.md index 7377a9123a..2537fb44fa 100644 --- a/docs/features/techdocs/README.md +++ b/docs/features/techdocs/README.md @@ -56,7 +56,7 @@ Spotify’s developer experience offering with 2,400+ documentation sites and [concepts]: concepts.md [reading documentation]: reading-documentation.md [writing documentation]: writing-documentation.md -[publishing documentation]: writing-and-publishing.md +[publishing documentation]: creating-and-publishing.md [contributing]: contributing.md [debugging]: debugging.md [faq]: FAQ.md 'Frequently asked questions' From fb3284a35bf2ee862eb3208192bc880618f88cb2 Mon Sep 17 00:00:00 2001 From: ellinors Date: Wed, 22 Jul 2020 11:55:16 +0200 Subject: [PATCH 3/3] fix(techdocs): clean up unused links --- docs/features/techdocs/README.md | 12 ++---------- 1 file changed, 2 insertions(+), 10 deletions(-) diff --git a/docs/features/techdocs/README.md b/docs/features/techdocs/README.md index 2537fb44fa..b6a4d82b92 100644 --- a/docs/features/techdocs/README.md +++ b/docs/features/techdocs/README.md @@ -36,11 +36,7 @@ Spotify’s developer experience offering with 2,400+ documentation sites and - [Getting Started] - [Concepts] -- [Reading Documentation] -- [Writing Documentation] -- [Publishing Documentation] -- [Contributing] -- [Debugging] +- [Creating and Publishing Documentation] - [FAQ] ## Tech Stack @@ -54,11 +50,7 @@ Spotify’s developer experience offering with 2,400+ documentation sites and [getting started]: getting-started.md [concepts]: concepts.md -[reading documentation]: reading-documentation.md -[writing documentation]: writing-documentation.md -[publishing documentation]: creating-and-publishing.md -[contributing]: contributing.md -[debugging]: debugging.md +[creating and publishing documentation]: creating-and-publishing.md [faq]: FAQ.md 'Frequently asked questions' [techdocs/frontend]: https://github.com/spotify/backstage/blob/master/plugins/techdocs