paulononato/backstage
1
0
Fork 0
Code Issues Pull Requests Actions 47 Packages Projects Releases Wiki Activity

Merge pull request #8007 from backstage/refactor/merge-back-techdocs-cli

Browse Source 
Tech Docs Command Line Reunification
This commit is contained in:
Eric Peterson
2021-11-17 13:00:48 +01:00
committed by GitHub
parent 937189f15a c0e64a685f
commit ec2c835afc
62 changed files with 3140 additions and 3 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/assets/features/techdocs/techdocs-cli-serve-preview.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 278 KiB

docs/features/techdocs/cli.md
+241
View File
@@ -0,0 +1,241 @@
# TechDocs CLI
Utility command line interface for managing TechDocs sites in
[Backstage](https://github.com/backstage/backstage).
https://backstage.io/docs/features/techdocs/techdocs-overview
## Features
- Supports local development/preview of a TechDocs site in a Backstage app.
- Supports generation and publishing of a documentation site in a CI/CD
workflow.
```bash
techdocs-cli --help
Usage: techdocs-cli [options] [command]
Options:
-V, --version output the version number
-h, --help display help for command
Commands:
generate|build [options] Generate TechDocs documentation site using mkdocs.
publish [options] Publish generated TechDocs site to an external storage AWS S3,
Google GCS, etc.
serve:mkdocs [options] Serve a documentation project locally using mkdocs serve.
serve [options] Serve a documentation project locally in a Backstage app-like
environment
help [command] display help for command
```
## Installation
You can always use [`npx`](https://github.com/npm/npx) to run the latest version
of `techdocs-cli` -
```bash
npx @techdocs/cli [command]
```
Or you can install it using [npm](https://www.npmjs.com/package/@techdocs/cli) -
```bash
npm install -g @techdocs/cli
techdocs-cli [command]
```
## Usage
### Preview TechDocs site locally in a Backstage like environment
```bash
techdocs-cli serve
```
![A preview of techdocs-cli serve command](../../assets/features/techdocs/techdocs-cli-serve-preview.png)
By default, Docker and
[techdocs-container](https://github.com/backstage/techdocs-container) is used to
make sure all the dependencies are installed. However, Docker can be disabled
with `--no-docker` flag.
The command starts two local servers - an MkDocs preview server on port 8000 and
a Backstage app server on port 3000. The Backstage app has a custom TechDocs API
implementation, which uses the MkDocs preview server as a proxy to fetch the
generated documentation files and assets.
NOTE: When using a custom `techdocs` docker image, make sure the entry point is
also `ENTRYPOINT ["mkdocs"]`.
Command reference:
```bash
Usage: techdocs-cli serve [options]
Serve a documentation project locally in a Backstage app-like environment
Options:
-i, --docker-image <DOCKER_IMAGE> The mkdocs docker container to use (default: "spotify/techdocs")
--no-docker Do not use Docker, use MkDocs executable in current user environment.
--mkdocs-port <PORT> Port for MkDocs server to use (default: "8000")
-v --verbose Enable verbose output. (default: false)
-h, --help display help for command
```
### Generate TechDocs site from a documentation project
```bash
techdocs-cli generate
```
Alias: `techdocs-cli build`
The generate command uses the
[`@backstage/techdocs-common`](https://github.com/backstage/backstage/tree/master/packages/techdocs-common)
package from Backstage for consistency. A Backstage app can also generate and
publish TechDocs sites if `techdocs.builder` is set to `'local'` in
`app-config.yaml`. See
[configuration reference](https://backstage.io/docs/features/techdocs/configuration).
By default, this command uses Docker and
[techdocs-container](https://github.com/backstage/techdocs-container) to make
sure all the dependencies are installed. But it can be disabled using
`--no-docker` flag.
Command reference:
```bash
techdocs-cli generate --help
Usage: techdocs-cli generate|build [options]
Generate TechDocs documentation site using MkDocs.
Options:
--source-dir <PATH> Source directory containing mkdocs.yml and docs/ directory. (default: ".")
--output-dir <PATH> Output directory containing generated TechDocs site. (default: "./site/")
--docker-image <DOCKER_IMAGE> The mkdocs docker container to use (default: "spotify/techdocs:v0.3.4")
--no-pull Do not pull the latest docker image
--no-docker Do not use Docker, use MkDocs executable and plugins in current user environment.
--techdocs-ref <HOST_TYPE:URL> The repository hosting documentation source files e.g.
github:https://ghe.mycompany.net.com/org/repo.
This value is same as the backstage.io/techdocs-ref annotation of the corresponding
Backstage entity.
It is completely fine to skip this as it is only being used to set repo_url in mkdocs.yml
if not found.
--etag <ETAG> A unique identifier for the prepared tree e.g. commit SHA. If provided it will be stored
in techdocs_metadata.json.
-v --verbose Enable verbose output. (default: false)
-h, --help display help for command
```
### Publish generated TechDocs sites
```bash
techdocs-cli publish --publisher-type <awsS3|googleGcs|azureBlobStorage> --storage-name <bucket/container name> --entity <namespace/kind/name>
```
After generating a TechDocs site using `techdocs-cli generate`, use the publish
command to upload the static generated files on a cloud storage (AWS/GCS) bucket
or (Azure) container which your Backstage app can read from.
The value for `--entity` must be the Backstage entity which the generated
TechDocs site belongs to. You can find the values in your Entity's
`catalog-info.yaml` file. If namespace is missing in the `catalog-info.yaml`,
use `default`. The directory structure used in the storage bucket is
`namespace/kind/name/<files>`.
Note that the values are case-sensitive. An example for `--entity` is
`default/Component/<entityName>`.
Command reference:
```bash
Usage: techdocs-cli publish [options]
Publish generated TechDocs site to an external storage AWS S3, Google GCS, etc.
Options:
--publisher-type <TYPE> (Required always) awsS3 | googleGcs | azureBlobStorage
- same as techdocs.publisher.type in Backstage
app-config.yaml
--storage-name <BUCKET/CONTAINER NAME> (Required always) In case of AWS/GCS, use the bucket
name. In case of Azure, use container name. Same as
techdocs.publisher.[TYPE].bucketName
--entity <NAMESPACE/KIND/NAME> (Required always) Entity uid separated by / in
namespace/kind/name order (case-sensitive). Example:
default/Component/myEntity
--legacyUseCaseSensitiveTripletPaths Publishes objects with cased entity triplet prefix when set (e.g. namespace/Kind/name).
Only use if your TechDocs backend is configured the same way
--azureAccountName <AZURE ACCOUNT NAME> (Required for Azure) specify when --publisher-type
azureBlobStorage
--azureAccountKey <AZURE ACCOUNT KEY> Azure Storage Account key to use for authentication.
If not specified, you must set AZURE_TENANT_ID,
AZURE_CLIENT_ID & AZURE_CLIENT_SECRET as environment
variables.
--awsRoleArn <AWS ROLE ARN> Optional AWS ARN of role to be assumed.
--awsEndpoint <AWS ENDPOINT> Optional AWS endpoint to send requests to.
--awsS3ForcePathStyle Optional AWS S3 option to force path style.
--directory <PATH> Path of the directory containing generated files to
publish (default: "./site/")
-h, --help display help for command
```
### Migrate content for case-insensitive access
Prior to the beta version of TechDocs (`v[0.11.0]`), TechDocs were stored in
object storage using a case-sensitive entity triplet (e.g.
`default/API/name/index.html`). This resulted in a limitation where that exact
case was required in the Backstage URL in order to read/render TechDocs content.
As of `v[0.11.0]` of the TechDocs plugin, any case is allowed in the URL (e.g.
`default/api/name`), matching the behavior of the Catalog plugin.
Backstage instances created with TechDocs `v[0.11.0]` or later do not need this
command. However, when upgrading to this version from an older version of
TechDocs, the `migrate` command can be used prior to deployment to ensure docs
remain accessible without having to rebuild all docs.
Prior to upgrading to `v[0.11.0]` or greater, run this command to copy all
assets to their lower-case triplet equivalents like this:
```bash
techdocs-cli migrate --publisher-type <awsS3|googleGcs|azureBlobStorage> --storage-name <bucket/container name> --verbose
```
Once migrated and the upgraded version of the Backstage plugin has been
deployed, you can clean up the legacy, case-sensitive triplet files by
re-running the command with the `--removeOriginal` flag passed, which _moves_
(rather than copies) the files. Note: this deletes files and is therefore a
destructive operation that should performed with caution.
```bash
techdocs-cli migrate --publisher-type <awsS3|googleGcs|azureBlobStorage> --storage-name <bucket/container name> --removeOriginal --verbose
```
Afterward, update your TechDocs CLI to `v[0.7.0]` to ensure further publishing
happens using a lower-case entity triplet.
Note: arguments for this command largely match those of the `publish` command,
depending on your chosen storage provider. Run `techdocs-cli migrate --help` for
details.
#### Authentication
You need to make sure that your environment is able to authenticate with the
target cloud provider. `techdocs-cli` uses the official Node.js clients provided
by AWS (v2), Google Cloud and Azure. You can authenticate using environment
variables and/or by other means (`~/.aws/credentials`, `~/.config/gcloud` etc.)
Refer to the Authentication section of the following documentation depending
upon your cloud storage provider -
- [Google Cloud Storage](https://backstage.io/docs/features/techdocs/using-cloud-storage#configuring-google-gcs-bucket-with-techdocs)
- [AWS S3](https://backstage.io/docs/features/techdocs/using-cloud-storage#configuring-aws-s3-bucket-with-techdocs)
- [Azure Blob Storage](https://backstage.io/docs/features/techdocs/using-cloud-storage#configuring-azure-blob-storage-container-with-techdocs)
## Development
You are welcome to contribute to TechDocs CLI to improve it and support new
features! See the project
[README](https://github.com/backstage/backstage/blob/main/src/packages/techdocs-cli/README.md)
for more information.