Publish api-server docs to ghpages (#704)

* deploy docs to ghpages

Signed-off-by: Teo Koon Peng <[email protected]>

* source rmf

Signed-off-by: Teo Koon Peng <[email protected]>

* try connect by ip

Signed-off-by: Teo Koon Peng <[email protected]>

* start server in new session

Signed-off-by: Teo Koon Peng <[email protected]>

* fix artifact path

Signed-off-by: Teo Koon Peng <[email protected]>

* update openapi.json path

Signed-off-by: Teo Koon Peng <[email protected]>

* update openapi.json path

Signed-off-by: Teo Koon Peng <[email protected]>

* update README

Signed-off-by: Teo Koon Peng <[email protected]>

* disable running action on testing branch

Signed-off-by: Teo Koon Peng <[email protected]>

* update paths

Signed-off-by: Teo Koon Peng <[email protected]>

* run only if files in api-server changes

Signed-off-by: Teo Koon Peng <[email protected]>

* undo testing changes

Signed-off-by: Teo Koon Peng <[email protected]>

* remove unused files

Signed-off-by: Teo Koon Peng <[email protected]>

* remove run on pr

Signed-off-by: Teo Koon Peng <[email protected]>

---------

Signed-off-by: Teo Koon Peng <[email protected]>

.github/workflows/ghpages.yml

@@ -0,0 +1,62 @@
+name: Deploy docs to Pages
+
+on:
+  # Runs on pushes targeting the default branch
+  push:
+    branches: ["main"]
+    paths:
+      - "packages/api-server/**"
+
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
+# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  # Single deploy job since we're just deploying
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    container:
+      image: ghcr.io/${{ github.repository }}/e2e
+      credentials:
+        username: ${{ github.repository_owner }}
+        password: ${{ secrets.GITHUB_TOKEN }}
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        shell: bash
+        working-directory: packages/api-server
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+      - name: Setup Pages
+        uses: actions/configure-pages@v3
+      - name: setup python
+        run: apt update && apt install -y python3-venv python-is-python3
+      - name: bootstrap
+        uses: ./.github/actions/bootstrap
+        with:
+          package: api-server
+      - name: Extract docs
+        run: |
+          . /rmf_demos_ws/install/setup.bash
+          pipenv run python3 scripts/extract_docs.py -o docs
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v1
+        with:
+          path: packages/api-server/docs
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v2

README.md

@@ -97,6 +97,12 @@ This launches a development server with the office world from `rmf_demos`. The s
 
 See the [rmf-dashboard](packages/dashboard/README.md#configuration) docs.
 
+## API Docs
+
+Docs for the api-server can be found at `/docs` relative to your server's url, e.g. `http://localhost:8000/docs`.
+
+The docs can also be found online at https://open-rmf.github.io/rmf-web/docs/api-server.
+
 ## Troubleshooting
 First thing to try is to build rmf from source, in order to speed up development, `rmf-web` may use in-development features of rmf. That means that the binary releases may not have the features required, sometimes the features `rmf-web` uses may be so new that not even the rolling releases has it.
 

packages/api-server/scripts/extract_docs.py

@@ -0,0 +1,50 @@
+import argparse
+import atexit
+import json
+import os.path
+import signal
+import subprocess
+import time
+from urllib.request import urlopen
+
+parser = argparse.ArgumentParser(
+    description="Extracts openapi docs from the api server. NOTE: Make sure the api server is not running before running this."
+)
+parser.add_argument("-o", "--output", help="output directory", required=True)
+args = parser.parse_args()
+
+server_proc = None
+
+
+def cleanup():
+    if server_proc:
+        pgid = os.getpgid(server_proc.pid)
+        os.killpg(pgid, signal.SIGTERM)
+        server_proc.wait()
+
+
+atexit.register(cleanup)
+server_proc = subprocess.Popen(
+    ("pnpm", "start"), cwd=f"{os.path.dirname(__file__)}/..", start_new_session=True
+)
+
+time.sleep(5)  # wait for server to be ready
+outdir = f"{args.output}/docs/api-server/"
+os.makedirs(outdir, exist_ok=True)
+
+with urlopen("http://127.0.0.1:8000/docs") as resp:
+    html: bytes = resp.read()
+    html = html.replace(b"/openapi.json", b"/rmf-web/docs/api-server/openapi.json")
+    with open(f"{outdir}/index.html", "bw") as f:
+        f.write(html)
+
+with urlopen("http://127.0.0.1:8000/openapi.json") as resp:
+    openapi = json.loads(resp.read())
+    openapi["servers"] = [
+        {
+            "url": "{url}",
+            "variables": {"url": {"default": "http://example.com"}},
+        }
+    ]
+    with open(f"{outdir}/openapi.json", "w") as f:
+        json.dump(openapi, f)