Vitepress build (#2490)

* Add vitepress core info

* Add docs source

* Docs deploy workflow

* Add yarn.lock

* Package lock - required by CI

* CSS for front page colors

* REmove package lock file to try fix my build errors

* Add yarn to build too

* remove yarn invocation

* New package.json attempt

* Attempt with frozen yarn lockfile

* Build for branches

* Update .github/workflows/docs_deploy.yml

Co-authored-by: Julian Oes <julian@oes.ch>

* Move docs into docs-relative path

* Fix config - base path and edit links

* update .gitignore

* only build docs on branches, not tags

* Attempt fix deploy build to use relative path

* Try find the lockfile

* Fix build - correct caching

---------

Co-authored-by: Julian Oes <julian@oes.ch>

.github/workflows/docs_deploy.yml

@@ -0,0 +1,78 @@
+name: Docs
+
+on:
+  push:
+    branches:
+      - main
+      - 'v*'
+    #tags:
+    #  - 'v*'
+    paths:
+      - 'docs/**'
+  pull_request:
+    paths:
+      - 'docs/**'
+
+  workflow_dispatch:
+
+env:
+  BRANCH_NAME: ${{ github.head_ref || github.ref_name }}
+
+jobs:
+  build:
+    runs-on: ubuntu-24.04
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: npm
+          # Specify the path to lock file for correct caching
+          cache-dependency-path: ./docs/yarn.lock
+
+      - name: Install dependencies
+        run: yarn install --frozen-lockfile --cwd ./docs
+
+      - name: Build with VitePress
+        working-directory: ./docs
+        run: |
+          npm run docs:build
+          touch .vitepress/dist/.nojekyll
+
+      - name: Upload artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: mavsdk_docs_build
+          path: docs/.vitepress/dist/
+          retention-days: 1
+
+  deploy:
+    if: ${{ github.event_name == 'push' || github.event_name == 'workflow_dispatch' || (github.event_name == 'pull_request' && github.event.pull_request.merged) }}
+    needs: build
+    runs-on: ubuntu-24.04
+
+    steps:
+      - name: Download Artifact
+        uses: actions/download-artifact@v4
+        with:
+          name: mavsdk_docs_build
+          path: ~/_book
+
+      - name: Deploy
+        env:
+          GIT_USER: ${{ secrets.PX4BUILDBOT_USER }}
+          GIT_PASS: ${{ secrets.PX4BUILDBOT_PASS }}
+        run: |
+          git clone https://${{ secrets.PX4BUILDBOT_USER }}:${{ secrets.PX4BUILDBOT_ACCESSTOKEN }}@github.com/mavlink/mavsdk.mavlink.io.git
+          rm -rf mavsdk.mavlink.io/${{ env.BRANCH_NAME }}
+          mkdir -p mavsdk.mavlink.io/${{ env.BRANCH_NAME }}
+          cp -r ~/_book/* mavsdk.mavlink.io/${{ env.BRANCH_NAME }}/
+          cd mavsdk.mavlink.io
+          git config user.email "bot@px4.io"
+          git config user.name "PX4BuildBot"
+          git add ${{ env.BRANCH_NAME }}
+          git commit -a -m "MAVSDK docs build update `date`"
+          git push origin master

.github/workflows/main.yml

@@ -6,10 +6,14 @@ on:
     - 'main'
     tags:
     - 'v*'
+    paths-ignore:
+    - 'docs/**'
   pull_request:
     branches:
     - '*'
-
+    paths-ignore:
+    - 'docs/**'
+    - '.github/workflows/docs_deploy.yml'
 
 jobs:
   coverage:

.gitignore

@@ -26,3 +26,9 @@ cmake-build-*
 # mavlink repo to generate mavlink-headers
 mavlink
 mavlink-headers
+
+
+# vitepress - Docs guide
+docs/node_modules/
+docs/.vitepress/cache/
+docs/.vitepress/dist/

docs/.vitepress/config.mjs

@@ -0,0 +1,203 @@
+import { defineConfig } from "vitepress";
+const getSidebar = require("./get_sidebar.js");
+
+// Tabs: https://github.com/Red-Asuka/vitepress-plugin-tabs
+import tabsPlugin from "@red-asuka/vitepress-plugin-tabs";
+
+// https://vitepress.dev/reference/site-config
+export default defineConfig({
+  title: "MAVSDK Guide",
+  description: "MAVSDK Guide",
+  base: process.env.BRANCH_NAME ? "/" + process.env.BRANCH_NAME + "/" : "",
+  srcExclude: [
+    "de/**/*.md",
+    "ja/**/*.md",
+    "ru/**/*.md",
+    "tr/**/*.md",
+    "ko/**/*.md",
+    "zh/**/*.md",
+    "uk/**/*.md",
+    "**/_*.md", //Remove source docs that start with "_" (included/not rendered)
+    "README.md", //Remove README.md in root directory
+  ],
+  ignoreDeadLinks: true,
+  markdown: {
+    math: true,
+    config: (md) => {
+      // use more markdown-it plugins!
+      tabsPlugin(md); //https://github.com/Red-Asuka/vitepress-plugin-tabs
+    },
+  },
+  locales: {
+    en: {
+      label: "English",
+      // other locale specific properties...
+      themeConfig: {
+        sidebar: getSidebar.sidebar("en"),
+
+        editLink: {
+          pattern: ({ filePath, frontmatter }) => {
+            if (frontmatter.newEditLink) {
+              //newEditLink defines a frontmatter key you can use to append a path to main
+              return `https://github.com/mavlink/MAVSDK/edit/main/docs/${frontmatter.newEditLink}`;
+            } else {
+              return `https://github.com/mavlink/MAVSDK/edit/main/docs/${filePath}`;
+            }
+          },
+          text: "Edit on GitHub",
+        },
+      },
+    },
+
+    /*
+    zh: {
+      label: "中文 (Chinese)",
+      lang: "zh-CN", // optional, will be added  as `lang` attribute on `html` tag
+      themeConfig: {
+        sidebar: getSidebar.sidebar("zh"),
+      },
+      // other locale specific properties...
+    },
+    ko: {
+      label: "한국어 (Korean)",
+      lang: "ko-KR", // optional, will be added  as `lang` attribute on `html` tag
+      themeConfig: {
+        sidebar: getSidebar.sidebar("ko"),
+      },
+
+      // other locale specific properties...
+    },
+    */
+  },
+
+  //
+
+  themeConfig: {
+    // https://vitepress.dev/reference/default-theme-config
+    siteTitle: false,
+    logo: {
+      light: "/site/logo_mavsdk_header_lightmode.png",
+      dark: "/site/logo_mavsdk_header_darkmode.png",
+      alt: "",
+    },
+    sidebar: getSidebar.sidebar("en"),
+    externalLinkIcon: true,
+
+    editLink: {
+      pattern: "https://crowdin.com/project/mavsdk",
+      text: "Edit translation on Crowdin",
+    },
+
+    search: {
+      provider: "local",
+    },
+
+    nav: [
+      {
+        text: "MAVSDK",
+        items: [
+          {
+            text: "Website",
+            link: "https://dronecode.org/sdk/",
+            ariaLabel: "MAVSDK website link",
+          },
+          {
+            text: "Source Code",
+            link: "https://github.com/mavlink/MAVSDK",
+          },
+        ],
+      },
+      {
+        text: "Dronecode",
+        items: [
+          {
+            text: "PX4",
+            link: "https://px4.io/",
+          },
+          {
+            text: "QGroundControl",
+            link: "http://qgroundcontrol.com/",
+          },
+          {
+            text: "MAVLINK",
+            link: "https://mavlink.io/en/",
+          },
+          {
+            text: "PX4 Guide",
+            link: "https://docs.px4.io/main/en/index.html",
+          },
+          {
+            text: "QGroundControl Guide",
+            link: "https://docs.qgroundcontrol.com/master/en/qgc-user-guide/",
+          },
+          {
+            text: "Dronecode Camera Manager",
+            link: "https://camera-manager.dronecode.org/en/",
+          },
+        ],
+      },
+      {
+        text: "Support",
+        link: "https://discuss.px4.io/c/mavsdk/19",
+      },
+      {
+        text: "Version",
+        items: [
+          {
+            text: "main",
+            link: "https://mavsdk.mavlink.io/main/en/cpp/api_changes.html",
+          },
+          {
+            text: "v2",
+            link: "https://mavsdk.mavlink.io/v2.0/en/cpp/api_changes.html",
+          },
+          {
+            text: "v1.4",
+            link: "https://mavsdk.mavlink.io/v1.4/en/cpp/api_changes.html",
+          },
+        ],
+      },
+    ],
+
+    socialLinks: [
+      { icon: "github", link: "https://github.com/mavlink/MAVSDK" },
+    ],
+  },
+
+  head: [
+    ["link", { rel: "icon", href: "/en/favicon.ico" }],
+    [
+      "script",
+      {
+        async: "",
+        src: "https://www.googletagmanager.com/gtag/js?id=G-91EWVWRQ93",
+      },
+    ],
+    [
+      "script",
+      {},
+      `window.dataLayer = window.dataLayer || [];
+      function gtag(){dataLayer.push(arguments);}
+      gtag('js', new Date());
+      gtag('config', 'G-91EWVWRQ93');`,
+    ],
+  ],
+
+  async transformPageData(pageData, { siteConfig }) {
+    //Logs every page loaded on build. Good way to catch errors not caught by other things.
+    console.log(pageData.filePath);
+
+    // Global variables as frontmatter
+    pageData.frontmatter.github_branch ??= process.env.BRANCH_NAME
+      ? process.env.BRANCH_NAME
+      : "main";
+  },
+
+  vue: {
+    template: {
+      compilerOptions: {
+        isCustomElement: (tag) => tag === "lite-youtube",
+      },
+    },
+  },
+});