From 4f709b4a250060097630c379e5dae08b1919b0c3 Mon Sep 17 00:00:00 2001 From: Bilawal Hameed Date: Fri, 10 Jul 2020 16:05:14 +0200 Subject: [PATCH 1/6] fix: migrate techdocs-container to packages/ --- .../mkdocs/container => packages/techdocs-container}/Dockerfile | 0 .../techdocs/mkdocs => packages/techdocs-container}/README.md | 0 .../mkdocs => packages/techdocs-container}/mock-docs/.gitignore | 0 .../techdocs-container}/mock-docs/docs/index.md | 0 .../mkdocs => packages/techdocs-container}/mock-docs/mkdocs.yml | 0 .../techdocs-container}/mock-docs/sub-docs/docs/index.md | 0 .../techdocs-container}/mock-docs/sub-docs/mkdocs.yml | 0 .../techdocs-container}/techdocs-core/.gitignore | 0 .../techdocs-container}/techdocs-core/README.md | 0 .../techdocs-container}/techdocs-core/requirements.txt | 0 .../techdocs-container}/techdocs-core/setup.py | 0 .../techdocs-container}/techdocs-core/src/__init__.py | 0 .../techdocs-container}/techdocs-core/src/core.py | 0 13 files changed, 0 insertions(+), 0 deletions(-) rename {plugins/techdocs/mkdocs/container => packages/techdocs-container}/Dockerfile (100%) rename {plugins/techdocs/mkdocs => packages/techdocs-container}/README.md (100%) rename {plugins/techdocs/mkdocs => packages/techdocs-container}/mock-docs/.gitignore (100%) rename {plugins/techdocs/mkdocs => packages/techdocs-container}/mock-docs/docs/index.md (100%) rename {plugins/techdocs/mkdocs => packages/techdocs-container}/mock-docs/mkdocs.yml (100%) rename {plugins/techdocs/mkdocs => packages/techdocs-container}/mock-docs/sub-docs/docs/index.md (100%) rename {plugins/techdocs/mkdocs => packages/techdocs-container}/mock-docs/sub-docs/mkdocs.yml (100%) rename {plugins/techdocs/mkdocs/container => packages/techdocs-container}/techdocs-core/.gitignore (100%) rename {plugins/techdocs/mkdocs/container => packages/techdocs-container}/techdocs-core/README.md (100%) rename {plugins/techdocs/mkdocs/container => packages/techdocs-container}/techdocs-core/requirements.txt (100%) rename {plugins/techdocs/mkdocs/container => packages/techdocs-container}/techdocs-core/setup.py (100%) rename {plugins/techdocs/mkdocs/container => packages/techdocs-container}/techdocs-core/src/__init__.py (100%) rename {plugins/techdocs/mkdocs/container => packages/techdocs-container}/techdocs-core/src/core.py (100%) diff --git a/plugins/techdocs/mkdocs/container/Dockerfile b/packages/techdocs-container/Dockerfile similarity index 100% rename from plugins/techdocs/mkdocs/container/Dockerfile rename to packages/techdocs-container/Dockerfile diff --git a/plugins/techdocs/mkdocs/README.md b/packages/techdocs-container/README.md similarity index 100% rename from plugins/techdocs/mkdocs/README.md rename to packages/techdocs-container/README.md diff --git a/plugins/techdocs/mkdocs/mock-docs/.gitignore b/packages/techdocs-container/mock-docs/.gitignore similarity index 100% rename from plugins/techdocs/mkdocs/mock-docs/.gitignore rename to packages/techdocs-container/mock-docs/.gitignore diff --git a/plugins/techdocs/mkdocs/mock-docs/docs/index.md b/packages/techdocs-container/mock-docs/docs/index.md similarity index 100% rename from plugins/techdocs/mkdocs/mock-docs/docs/index.md rename to packages/techdocs-container/mock-docs/docs/index.md diff --git a/plugins/techdocs/mkdocs/mock-docs/mkdocs.yml b/packages/techdocs-container/mock-docs/mkdocs.yml similarity index 100% rename from plugins/techdocs/mkdocs/mock-docs/mkdocs.yml rename to packages/techdocs-container/mock-docs/mkdocs.yml diff --git a/plugins/techdocs/mkdocs/mock-docs/sub-docs/docs/index.md b/packages/techdocs-container/mock-docs/sub-docs/docs/index.md similarity index 100% rename from plugins/techdocs/mkdocs/mock-docs/sub-docs/docs/index.md rename to packages/techdocs-container/mock-docs/sub-docs/docs/index.md diff --git a/plugins/techdocs/mkdocs/mock-docs/sub-docs/mkdocs.yml b/packages/techdocs-container/mock-docs/sub-docs/mkdocs.yml similarity index 100% rename from plugins/techdocs/mkdocs/mock-docs/sub-docs/mkdocs.yml rename to packages/techdocs-container/mock-docs/sub-docs/mkdocs.yml diff --git a/plugins/techdocs/mkdocs/container/techdocs-core/.gitignore b/packages/techdocs-container/techdocs-core/.gitignore similarity index 100% rename from plugins/techdocs/mkdocs/container/techdocs-core/.gitignore rename to packages/techdocs-container/techdocs-core/.gitignore diff --git a/plugins/techdocs/mkdocs/container/techdocs-core/README.md b/packages/techdocs-container/techdocs-core/README.md similarity index 100% rename from plugins/techdocs/mkdocs/container/techdocs-core/README.md rename to packages/techdocs-container/techdocs-core/README.md diff --git a/plugins/techdocs/mkdocs/container/techdocs-core/requirements.txt b/packages/techdocs-container/techdocs-core/requirements.txt similarity index 100% rename from plugins/techdocs/mkdocs/container/techdocs-core/requirements.txt rename to packages/techdocs-container/techdocs-core/requirements.txt diff --git a/plugins/techdocs/mkdocs/container/techdocs-core/setup.py b/packages/techdocs-container/techdocs-core/setup.py similarity index 100% rename from plugins/techdocs/mkdocs/container/techdocs-core/setup.py rename to packages/techdocs-container/techdocs-core/setup.py diff --git a/plugins/techdocs/mkdocs/container/techdocs-core/src/__init__.py b/packages/techdocs-container/techdocs-core/src/__init__.py similarity index 100% rename from plugins/techdocs/mkdocs/container/techdocs-core/src/__init__.py rename to packages/techdocs-container/techdocs-core/src/__init__.py diff --git a/plugins/techdocs/mkdocs/container/techdocs-core/src/core.py b/packages/techdocs-container/techdocs-core/src/core.py similarity index 100% rename from plugins/techdocs/mkdocs/container/techdocs-core/src/core.py rename to packages/techdocs-container/techdocs-core/src/core.py From 3e1efc1e43ced03e9b3d2e1ce20a00f725e4ce8d Mon Sep 17 00:00:00 2001 From: Bilawal Hameed Date: Fri, 10 Jul 2020 16:06:45 +0200 Subject: [PATCH 2/6] fix(.github/workflows): add packages/techdocs-container --- .github/workflows/techdocs.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/.github/workflows/techdocs.yml b/.github/workflows/techdocs.yml index 505f63c879..75dc43fba1 100644 --- a/.github/workflows/techdocs.yml +++ b/.github/workflows/techdocs.yml @@ -4,6 +4,7 @@ on: pull_request: paths: - '.github/workflows/techdocs.yml' + - 'packages/techdocs-container/**' - 'packages/techdocs-cli/**' - 'plugins/techdocs/**' - 'plugins/techdocs-backend/**' From decf400b4b9b4e389e7e910fff5b0f2b47f24386 Mon Sep 17 00:00:00 2001 From: Bilawal Hameed Date: Fri, 10 Jul 2020 16:11:11 +0200 Subject: [PATCH 3/6] fix(.github/workflows): only validate Dockerfile, not publish (it happens via webhooks) --- .github/workflows/techdocs.yml | 9 ++------- 1 file changed, 2 insertions(+), 7 deletions(-) diff --git a/.github/workflows/techdocs.yml b/.github/workflows/techdocs.yml index 75dc43fba1..a313a89f5b 100644 --- a/.github/workflows/techdocs.yml +++ b/.github/workflows/techdocs.yml @@ -29,13 +29,8 @@ jobs: - name: Build and push Docker images uses: docker/build-push-action@v1.1.0 with: - path: plugins/techdocs/mkdocs/container - registry: docker.pkg.github.com - repository: ${{ github.repository }}/mkdocs - username: ${{ github.actor }} - password: ${{ github.token }} - tag_with_ref: true - push: true + path: packages/techdocs-container + push: false # Lint Python code for techdocs-core package - name: prepare python environment From 68d472f702a7c61bc9b4a7a5b6e5d20d628df1ee Mon Sep 17 00:00:00 2001 From: Bilawal Hameed Date: Fri, 10 Jul 2020 16:17:22 +0200 Subject: [PATCH 4/6] 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: From f5a5fac7cffed131bd19374a0e264eceab933f89 Mon Sep 17 00:00:00 2001 From: Bilawal Hameed Date: Fri, 10 Jul 2020 16:18:16 +0200 Subject: [PATCH 5/6] docs: correction --- .github/workflows/techdocs.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/techdocs.yml b/.github/workflows/techdocs.yml index 8c13915ebd..491b5693de 100644 --- a/.github/workflows/techdocs.yml +++ b/.github/workflows/techdocs.yml @@ -26,7 +26,7 @@ jobs: - uses: actions/checkout@v2 # Build Docker Image - - name: Build and push Docker images + - name: Build Docker image uses: docker/build-push-action@v1.1.0 with: path: packages/techdocs-container From 449c962aea15d5e0d76928c0e8f14a388f3735fa Mon Sep 17 00:00:00 2001 From: Bilawal Hameed Date: Fri, 10 Jul 2020 16:21:51 +0200 Subject: [PATCH 6/6] docs: removed prefix slash --- plugins/techdocs/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/plugins/techdocs/README.md b/plugins/techdocs/README.md index fb30f463dd..b763679a1c 100644 --- a/plugins/techdocs/README.md +++ b/plugins/techdocs/README.md @@ -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 `/packages/techdocs-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: