Merge pull request #2434 from spotify/orkohunter/update-techdocs-documentation
This commit is contained in:
Himanshu Mishra
@@ -6,14 +6,11 @@ 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)
|
||||
- [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?
|
||||
|
||||
@@ -30,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.
|
||||
|
||||
@@ -8,16 +8,21 @@ sidebar_label: Overview
|
||||
|
||||
<!-- Intro, backstory, etc.: -->
|
||||
|
||||
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
|
||||
@@ -101,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
|
||||
|
||||
|
||||
|
||||
@@ -0,0 +1,6 @@
|
||||
---
|
||||
id: architecture
|
||||
title: Architecture
|
||||
---
|
||||
|
||||
|
||||
@@ -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)
|
||||
|
||||
|
||||
@@ -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 ~/<repository-path>/
|
||||
cd /path/to/docs-repository/
|
||||
npx @techdocs/cli serve
|
||||
```
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -74,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.
|
||||
@@ -87,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.
|
||||
|
||||
|
||||
@@ -62,11 +62,12 @@
|
||||
},
|
||||
{
|
||||
"type": "subcategory",
|
||||
"label": "Docs-like-code",
|
||||
"label": "TechDocs",
|
||||
"ids": [
|
||||
"features/techdocs/techdocs-overview",
|
||||
"features/techdocs/getting-started",
|
||||
"features/techdocs/concepts",
|
||||
"features/techdocs/architecture",
|
||||
"features/techdocs/creating-and-publishing",
|
||||
"features/techdocs/faqs"
|
||||
]
|
||||
|
||||
+2
-1
@@ -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:
|
||||
|
||||
Reference in New Issue
Block a user