From 68d472f702a7c61bc9b4a7a5b6e5d20d628df1ee Mon Sep 17 00:00:00 2001 From: Bilawal Hameed Date: Fri, 10 Jul 2020 16:17:22 +0200 Subject: [PATCH] docs: updated to packages/techdocs-container --- .github/workflows/techdocs.yml | 2 +- packages/techdocs-cli/README.md | 12 ++++++------ packages/techdocs-container/README.md | 18 +++++++++++++----- .../techdocs-container/techdocs-core/README.md | 2 +- plugins/techdocs/README.md | 4 ++-- 5 files changed, 23 insertions(+), 15 deletions(-) diff --git a/.github/workflows/techdocs.yml b/.github/workflows/techdocs.yml index a313a89f5b..8c13915ebd 100644 --- a/.github/workflows/techdocs.yml +++ b/.github/workflows/techdocs.yml @@ -19,7 +19,7 @@ jobs: python-version: [3.7] env: - TECHDOCS_CORE_PATH: ./plugins/techdocs/mkdocs/container/techdocs-core + TECHDOCS_CORE_PATH: ./packages/techdocs-container/techdocs-core name: Python ${{ matrix.node-version }} on ${{ matrix.os }} steps: diff --git a/packages/techdocs-cli/README.md b/packages/techdocs-cli/README.md index f751497e83..fa862d5e2b 100644 --- a/packages/techdocs-cli/README.md +++ b/packages/techdocs-cli/README.md @@ -16,25 +16,25 @@ yarn serve:mkdocs ## Getting Started -You'll need Docker installed and running to use this. You will also need to build the container located at `plugins/techdocs/mkdocs/container` under the tag `mkdocs:local-dev`, as you can see in the commands from below: +You'll need Docker installed and running to use this. You will also need to build the container located at `/packages/techdocs-container` under the tag `mkdocs:local-dev`, as you can see in the commands from below: ```bash -docker build plugins/techdocs/mkdocs/container -t mkdocs:local-dev +docker build packages/techdocs-container -t mkdocs:local-dev ``` From that point, you can invoke the CLI from any project with a docs folder. Try out our example! ```bash -cd plugins/techdocs/mkdocs/mock-docs +cd packages/techdocs-container/mock-docs npx @techdocs/cli serve ``` ## Local Development -You'll need Docker installed and running to use this. You will also need to build the container located at `plugins/techdocs/mkdocs/container` under the tag `mkdocs:local-dev`, as you can see in the commands from below: +You'll need Docker installed and running to use this. You will also need to build the container located at `packages/techdocs-container` under the tag `mkdocs:local-dev`, as you can see in the commands from below: ```bash -docker build plugins/techdocs/mkdocs/container -t mkdocs:local-dev +docker build packages/techdocs-container -t mkdocs:local-dev ``` Once that is built, you'll need to manually create an `alias` for running the CLI locally: @@ -52,7 +52,7 @@ alias techdocs="[HERE]" From that point, you can invoke `techdocs` from any project with a docs folder. Try out our example! ```bash -cd plugins/techdocs/mkdocs/mock-docs +cd packages/techdocs-container/mock-docs techdocs serve ``` diff --git a/packages/techdocs-container/README.md b/packages/techdocs-container/README.md index 5c2a7725aa..01cbcc1992 100644 --- a/packages/techdocs-container/README.md +++ b/packages/techdocs-container/README.md @@ -1,15 +1,23 @@ -# MkDocs +# techdocs-container -Welcome to MkDocs. This is the TechDocs implementation of MkDocs. +This is the Docker container that powers the creation of static documentation sites that are supported by [TechDocs](https://github.com/spotify/backstage/blob/master/plugins/techdocs). **WIP: This is a work in progress. It is not ready for use yet. Follow our progress on [the Backstage Discord](https://discord.gg/MUpMjP2) under #docs-like-code or on [our GitHub Milestone](https://github.com/spotify/backstage/milestone/15).** -## Getting started +## Getting Started + +Using the TechDocs CLI, we can invoke the latest version of `techdocs-container` via Docker Hub: ```bash -docker build ./container -t mkdocs-container +npx @techdocs/cli serve:container +``` -docker run -w /content -v $(pwd)/mock-docs:/content -p 8000:8000 -it mkdocs-container serve -a 0.0.0.0:8000 +## Local Development + +```bash +docker build ./container -t techdocs-container + +docker run -w /content -v $(pwd)/mock-docs:/content -p 8000:8000 -it techdocs-container serve -a 0.0.0.0:8000 ``` Then open up `http://localhost:8000` on your local machine. diff --git a/packages/techdocs-container/techdocs-core/README.md b/packages/techdocs-container/techdocs-core/README.md index 143acf3c3b..12b3acb1e2 100644 --- a/packages/techdocs-container/techdocs-core/README.md +++ b/packages/techdocs-container/techdocs-core/README.md @@ -33,7 +33,7 @@ You'll then have the `techdocs-core` package available to use in Mkdocs and `pip In the parent `Dockerfile` we add this folder to the build and install the package locally in the container. In the future, we'll probably move away from this approach and have it download directly from a Python registry (and this folder will publish to one). -See the `README.md` located in the `mkdocs/` folder for more details on how to build and run the Docker container. +See the `README.md` located in the `techdocs-container/` folder for more details on how to build and run the Docker container. ## Linting diff --git a/plugins/techdocs/README.md b/plugins/techdocs/README.md index 8ac34f1943..fb30f463dd 100644 --- a/plugins/techdocs/README.md +++ b/plugins/techdocs/README.md @@ -20,7 +20,7 @@ It is only meant for local development, and the setup for it can be found inside ### Custom Storage URL -TechDocs currently reads a static HTML file, generated by Mkdocs (see our `plugins/techdocs/mkdocs/container` folder for more documentation) and stored on an external server, and loads that into Backstage. By default, we have set up a mock server with some example documentation sites over in Google Cloud Storage: +TechDocs currently reads a static HTML file, generated by Mkdocs (see our `packages/techdocs-container` folder for more documentation) and stored on an external server, and loads that into Backstage. By default, we have set up a mock server with some example documentation sites over in Google Cloud Storage: ```md # Base URL @@ -36,7 +36,7 @@ https://techdocs-mock-sites.storage.googleapis.com/mkdocs/index.html https://techdocs-mock-sites.storage.googleapis.com/backstage-microsite/index.html ``` -Using your own setup (or ours which is being worked on as of Q3 2020), you can point it to your own server with your own hosted documentation sites. The only requirement is that it the output is from [Mkdocs](https://mkdocs.org) with the Material theme. You can always use our documentation generation tool located at `plugins/techdocs/mkdocs/container` for easy setup. +Using your own setup (or ours which is being worked on as of Q3 2020), you can point it to your own server with your own hosted documentation sites. The only requirement is that it the output is from [Mkdocs](https://mkdocs.org) with the Material theme. You can always use our documentation generation tool located at `/packages/techdocs-container` for easy setup. To point TechDocs to your own server, simply update the `techdocs.storageUrl` value in your `app-config.yaml` file or set the environment variable `APP_CONFIG_techdocs_storageUrl` in your application: