diff --git a/.github/workflows/techdocs.yml b/.github/workflows/techdocs.yml index 505f63c879..491b5693de 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/**' @@ -18,23 +19,18 @@ 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: - 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: 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 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/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/packages/techdocs-container/README.md b/packages/techdocs-container/README.md new file mode 100644 index 0000000000..01cbcc1992 --- /dev/null +++ b/packages/techdocs-container/README.md @@ -0,0 +1,23 @@ +# techdocs-container + +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 + +Using the TechDocs CLI, we can invoke the latest version of `techdocs-container` via Docker Hub: + +```bash +npx @techdocs/cli serve:container +``` + +## 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/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 91% rename from plugins/techdocs/mkdocs/container/techdocs-core/README.md rename to packages/techdocs-container/techdocs-core/README.md index 143acf3c3b..12b3acb1e2 100644 --- a/plugins/techdocs/mkdocs/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/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 diff --git a/plugins/techdocs/README.md b/plugins/techdocs/README.md index 8ac34f1943..b763679a1c 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: diff --git a/plugins/techdocs/mkdocs/README.md b/plugins/techdocs/mkdocs/README.md deleted file mode 100644 index 5c2a7725aa..0000000000 --- a/plugins/techdocs/mkdocs/README.md +++ /dev/null @@ -1,15 +0,0 @@ -# MkDocs - -Welcome to MkDocs. This is the TechDocs implementation of MkDocs. - -**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 - -```bash -docker build ./container -t mkdocs-container - -docker run -w /content -v $(pwd)/mock-docs:/content -p 8000:8000 -it mkdocs-container serve -a 0.0.0.0:8000 -``` - -Then open up `http://localhost:8000` on your local machine.