From 7da352e2000113ee7c9f5c0e79f5d8671be6435c Mon Sep 17 00:00:00 2001 From: Himanshu Mishra Date: Fri, 11 Sep 2020 23:20:44 +0200 Subject: [PATCH 1/9] Use TechDocs instead of docs-like-code --- microsite/sidebars.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/microsite/sidebars.json b/microsite/sidebars.json index 7b4c852f4d..06e3c0c925 100644 --- a/microsite/sidebars.json +++ b/microsite/sidebars.json @@ -62,7 +62,7 @@ }, { "type": "subcategory", - "label": "Docs-like-code", + "label": "TechDocs", "ids": [ "features/techdocs/techdocs-overview", "features/techdocs/getting-started", From 64d2edc097018ce6a049305a51096023c9b7452c Mon Sep 17 00:00:00 2001 From: Himanshu Mishra Date: Fri, 11 Sep 2020 23:35:32 +0200 Subject: [PATCH 2/9] Updates to the TechDocs overview page - Add a one line context to what docs-like-code means - Add link to announcement blog post which is very in-depth about TechDocs - Milestone update and typo --- docs/features/techdocs/README.md | 19 ++++++++++++------- 1 file changed, 12 insertions(+), 7 deletions(-) diff --git a/docs/features/techdocs/README.md b/docs/features/techdocs/README.md index a7af6cc503..626bf0afd9 100644 --- a/docs/features/techdocs/README.md +++ b/docs/features/techdocs/README.md @@ -8,16 +8,21 @@ sidebar_label: Overview -Wait, what is TechDocs? TechDocs is Spotify’s homegrown docs-like-code solution -built directly into Backstage. Today, it is now one of the core products in -Spotify’s developer experience offering with 2,400+ documentation sites and -1,000+ engineers using it daily. +TechDocs is Spotify’s homegrown docs-like-code solution built directly into +Backstage. This means engineers write their documentation in Markdown files +which live together with their code. + +Today, it is one of the core products in Spotify’s developer experience offering +with 2,400+ documentation sites and 1,000+ engineers using it daily. Read more +about TechDocs and the philosophy in its +[announcement blog post](https://backstage.io/blog/2020/09/08/announcing-tech-docs). +🎉 ## Features -- A centralized place to discover documentation. +- A centralized place to discover and read documentation. -- A clear end-to-end docs-like-code solution. (_Coming soon in V.1_) +- A clear end-to-end docs-like-code solution. - A tightly coupled feedback loop with the developer workflow. (_Coming soon in V.3_) @@ -44,7 +49,7 @@ Spotify’s developer experience offering with 2,400+ documentation sites and #### TechDocs V.0 - As a user I can navigate to a manually curated docs explore page. -- As a user I can navigte to and read mock documentation that is manually +- As a user I can navigate to and read mock documentation that is manually uploaded by the TechDocs core team. #### TechDocs V.1 From a5e6e17fd37429a862c8ad0bd0a8faa4b1965662 Mon Sep 17 00:00:00 2001 From: Himanshu Mishra Date: Fri, 11 Sep 2020 23:38:34 +0200 Subject: [PATCH 3/9] Avoid duplication, redirect to Backstage getting started --- docs/features/techdocs/getting-started.md | 31 ++--------------------- 1 file changed, 2 insertions(+), 29 deletions(-) diff --git a/docs/features/techdocs/getting-started.md b/docs/features/techdocs/getting-started.md index 33edfecbe8..fb87315763 100644 --- a/docs/features/techdocs/getting-started.md +++ b/docs/features/techdocs/getting-started.md @@ -6,35 +6,8 @@ title: Getting Started TechDocs functions as a plugin to Backstage, so you will need to use Backstage to use TechDocs. -## What is Backstage? - -Backstage is an open platform for building developer portals. It’s based on the -developer portal we’ve been using internally at Spotify for over four years. -[Read more here](https://github.com/spotify/backstage). - -## Prerequisities - -In order to use Backstage and TechDocs, you need to have the following -installed: - -- [Node.js](https://nodejs.org) Active LTS (long term support), currently v12 -- [Yarn](https://yarnpkg.com/getting-started/install) - -## Creating a new Backstage app - -> If you have already created a Backstage application, jump to -> [Installing TechDocs](#installing-techdocs), otherwise complete this step. - -To create a new Backstage application for TechDocs, run the following command: - -```bash -npx @backstage/create-app -``` - -You will then be prompted to enter a name for your application. Once that's -done, a new Backstage application will be created in a new folder. For example, -if you choose the name `hello-world`, a new `hello-world` folder is created -containing your new Backstage application. +If you haven't setup Backstage already, start +[here](../../getting-started/index.md). ## Installing TechDocs From 08856c7da973a1034b9aa46fa8659b1c7e5d62be Mon Sep 17 00:00:00 2001 From: Himanshu Mishra Date: Fri, 11 Sep 2020 23:54:28 +0200 Subject: [PATCH 4/9] Add TechDocs architecture page --- docs/features/techdocs/architecture.md | 6 ++++++ microsite/sidebars.json | 1 + 2 files changed, 7 insertions(+) create mode 100644 docs/features/techdocs/architecture.md diff --git a/docs/features/techdocs/architecture.md b/docs/features/techdocs/architecture.md new file mode 100644 index 0000000000..4e063a8559 --- /dev/null +++ b/docs/features/techdocs/architecture.md @@ -0,0 +1,6 @@ +--- +id: architecture +title: Architecture +--- + +![TechDocs Big Picture](../../assets/techdocs/techdocs_big_picture.png) diff --git a/microsite/sidebars.json b/microsite/sidebars.json index 06e3c0c925..849cd56179 100644 --- a/microsite/sidebars.json +++ b/microsite/sidebars.json @@ -67,6 +67,7 @@ "features/techdocs/techdocs-overview", "features/techdocs/getting-started", "features/techdocs/concepts", + "features/techdocs/architecture", "features/techdocs/creating-and-publishing", "features/techdocs/faqs" ] From 506d130854919dc23812b49e534c83564edc48f6 Mon Sep 17 00:00:00 2001 From: Himanshu Mishra Date: Fri, 11 Sep 2020 23:55:01 +0200 Subject: [PATCH 5/9] Some minor improvements to docs --- docs/features/techdocs/README.md | 4 ---- docs/features/techdocs/concepts.md | 6 +++--- docs/features/techdocs/getting-started.md | 6 +++--- 3 files changed, 6 insertions(+), 10 deletions(-) diff --git a/docs/features/techdocs/README.md b/docs/features/techdocs/README.md index 626bf0afd9..03f3d452f4 100644 --- a/docs/features/techdocs/README.md +++ b/docs/features/techdocs/README.md @@ -106,7 +106,3 @@ more to come... https://github.com/spotify/backstage/blob/master/packages/techdocs-container [techdocs/cli]: https://github.com/spotify/backstage/blob/master/packages/techdocs-cli - -## TechDocs Big Picture - -![TechDocs Big Picture](../..//assets/techdocs/techdocs_big_picture.png) diff --git a/docs/features/techdocs/concepts.md b/docs/features/techdocs/concepts.md index 2fa84cebd6..8f5558c0f8 100644 --- a/docs/features/techdocs/concepts.md +++ b/docs/features/techdocs/concepts.md @@ -8,9 +8,9 @@ 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. +The TechDocs Core Plugin is an [MkDocs](https://www.mkdocs.org/) plugin created +as a wrapper around multiple MkDocs plugins and Python Markdown extensions to +standardize the configuration of MkDocs used for TechDocs. [TechDocs Core](https://github.com/spotify/backstage/blob/master/packages/techdocs-container/techdocs-core/README.md) diff --git a/docs/features/techdocs/getting-started.md b/docs/features/techdocs/getting-started.md index fb87315763..174894b020 100644 --- a/docs/features/techdocs/getting-started.md +++ b/docs/features/techdocs/getting-started.md @@ -47,7 +47,7 @@ export { plugin as TechDocs } from '@backstage/plugin-techdocs'; ### Setting the configuration TechDocs allows for configuration of the docs storage URL through your -`app-config` file. We provide two different values to be configured, +`app-config.yaml` file. We provide two different values to be configured, `requestUrl` and `storageUrl`. The `requestUrl` is what the reader will request its data from, and `storageUrl` is where the backend can find the stored documentation. @@ -60,13 +60,13 @@ techdocs: requestUrl: http://localhost:7000/techdocs/docs ``` -If you want `techdocs-backend` to manage building and publishing you want +If you want `techdocs-backend` to manage building and publishing, you want `requestUrl` to point to the default value (or wherever `techdocs-backend` is hosted). `storageUrl` should be where your publisher publishes your docs. Using the default `LocalPublish` that is the default value. If you have a setup where you are not using `techdocs-backend` for managing -building and publishing of your documentation you want to change the +building and publishing of your documentation, you want to change the `requestUrl` to point to your storage. In this case `storageUrl` is not required. From 7bdcd2ee5b701187c00413d8862d8633e91d2ad2 Mon Sep 17 00:00:00 2001 From: Himanshu Mishra Date: Fri, 11 Sep 2020 23:55:13 +0200 Subject: [PATCH 6/9] Update mkdocks.yml for Techdocs rendering of the docs --- mkdocs.yml | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/mkdocs.yml b/mkdocs.yml index 10cd7df9b2..c9fa1b7700 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -43,10 +43,11 @@ nav: - Create your own Templater: 'features/software-templates/extending/create-your-own-templater.md' - Create your own Publisher: 'features/software-templates/extending/create-your-own-publisher.md' - Create your own Preparer: 'features/software-templates/extending/create-your-own-preparer.md' - - Docs-like-code: + - TechDocs: - Overview: 'features/techdocs/README.md' - Getting Started: 'features/techdocs/getting-started.md' - Concepts: 'features/techdocs/concepts.md' + - TechDocs Architecture: 'features/techdocs/architecture.md' - Creating and Publishing Documentation: 'features/techdocs/creating-and-publishing.md' - FAQ: 'features/techdocs/FAQ.md' - Plugins: From 7b1b539e8cb5bdc670d5d0caeea09c81ac340b35 Mon Sep 17 00:00:00 2001 From: Himanshu Mishra Date: Sat, 12 Sep 2020 00:00:40 +0200 Subject: [PATCH 7/9] Remove the manual edit instructions There is an edit button on the website --- docs/features/techdocs/FAQ.md | 4 ---- 1 file changed, 4 deletions(-) diff --git a/docs/features/techdocs/FAQ.md b/docs/features/techdocs/FAQ.md index 8c716313bb..fad7e104dc 100644 --- a/docs/features/techdocs/FAQ.md +++ b/docs/features/techdocs/FAQ.md @@ -6,10 +6,6 @@ sidebar_label: FAQ This page answers frequently asked questions about [TechDocs](README.md). -_Got a question that you think others might be interested in knowing the answer -to? Edit this file -[here](https://github.com/spotify/backstage/edit/master/docs/features/techdocs/FAQ.md)._ - ## Technology - [What static site generator is TechDocs using?](#what-static-site-generator-is-techdocs-using) From e87263e83947a482dcde8f4403061ca89074f9c9 Mon Sep 17 00:00:00 2001 From: Himanshu Mishra Date: Sat, 12 Sep 2020 00:01:11 +0200 Subject: [PATCH 8/9] Some minor improvements to docs --- docs/features/techdocs/creating-and-publishing.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/features/techdocs/creating-and-publishing.md b/docs/features/techdocs/creating-and-publishing.md index 0dfa40f819..89df2fb18e 100644 --- a/docs/features/techdocs/creating-and-publishing.md +++ b/docs/features/techdocs/creating-and-publishing.md @@ -11,7 +11,7 @@ This section will guide you through: - [Manually add documentation setup to already existing repository](#manually-add-documentation-setup-to-already-existing-repository) - [Writing and previewing your documentation](#writing-and-previewing-your-documentation) -## Prerequisities +## Prerequisites - A working Backstage instance with TechDocs installed (see [TechDocs getting started](getting-started.md)) @@ -81,12 +81,12 @@ updated documentation next time you run Backstage! ## 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. +instance and get live reload on changes. This is useful when you want to preview +your documentation while writing. To do this you can run: ```bash -cd ~// +cd /path/to/docs-repository/ npx @techdocs/cli serve ``` From b1051d50e80196c494f5b34819dbf7797261452b Mon Sep 17 00:00:00 2001 From: Himanshu Mishra Date: Sat, 12 Sep 2020 00:09:07 +0200 Subject: [PATCH 9/9] Add FAQ about file formats --- docs/features/techdocs/FAQ.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/docs/features/techdocs/FAQ.md b/docs/features/techdocs/FAQ.md index fad7e104dc..cae0288889 100644 --- a/docs/features/techdocs/FAQ.md +++ b/docs/features/techdocs/FAQ.md @@ -10,6 +10,7 @@ This page answers frequently asked questions about [TechDocs](README.md). - [What static site generator is TechDocs using?](#what-static-site-generator-is-techdocs-using) - [What is the mkdocs-techdocs-core plugin?](#what-is-the-mkdocs-techdocs-core-plugin) +- [Does TechDocs support file formats other than Markdown (e.g. rst, asciidoc)?](#does-techdocs-support-file-formats-other-than-markdown-eg-rst-asciidoc-) #### What static site generator is TechDocs using? @@ -26,3 +27,10 @@ package is a MkDocs Plugin that works like a wrapper around multiple MkDocs plugins (e.g. [MkDocs Monorepo Plugin](https://github.com/spotify/mkdocs-monorepo-plugin)) as well as a selection of Python Markdown extensions that TechDocs supports. + +#### Does TechDocs support file formats other than Markdown (e.g. rst, asciidoc) ? + +Not right now. We are currently using MkDocs to generate the documentation from +source. So, they have to be in Markdown format. However, in future we want to +support other alternatives to MkDocs. That will make it possible to use other +file formats.