docs: updated to packages/techdocs-container

2020-07-10 16:17:22 +02:00
parent decf400b4b
commit 68d472f702
5 changed files with 23 additions and 15 deletions
@@ -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:
@@ -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
 ```

@@ -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.
@@ -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

@@ -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: