Introduce runner documentations (#133)

This PR introduces documentation for Runner.

<img width="959" alt="图片.png" src="attachments/5ad6a8af-d799-4718-9d33-56bf91a8852e">

Co-authored-by: kerwin612 <kerwin612@qq.com>
Reviewed-on: https://gitea.com/gitea/docs/pulls/133
Reviewed-by: Bo-Yi Wu (吳柏毅) <appleboy.tw@gmail.com>
Co-authored-by: Lunny Xiao <xiaolunwen@gmail.com>
Co-committed-by: Lunny Xiao <xiaolunwen@gmail.com>

docusaurus.config.js

@@ -162,7 +162,42 @@ const config = {
       {
         domain: 'docs.gitea.com',
       },
-    ]
+    ],
+
+    // for runner documentations
+    [
+      '@docusaurus/plugin-content-docs',
+      {
+        id: 'runner',
+        path: 'runner',
+        routeBasePath: 'runner',
+        //sidebarPath: './runner/sidebars.js',
+        versions: {
+          current: {
+            label: 'main',
+            banner: 'unreleased',
+          },
+          "0.2.11": {
+            path: '0.2.11',
+            label: '0.2.11',
+          }
+        },
+        lastVersion: '0.2.11',
+        editUrl: ({versionDocsDirPath, docPath, locale, version, permalink}) => {
+          return `https://gitea.com/gitea/docs/src/branch/main/${version === 'current' ? 'runner': `runner_versioned_docs/version-${version}`}/${docPath}`;
+        },
+        async sidebarItemsGenerator({defaultSidebarItemsGenerator, ...args}) {
+          const {item} = args;
+          // Use the provided data to generate a custom sidebar slice
+          const sidebarItems = await defaultSidebarItemsGenerator(args);
+          if (item.dirName !== 'usage') {
+            return sidebarItems;
+          } else {
+            return sortItemsByCategory(sidebarItems);
+          }
+        },
+      },
+    ],
   ],
 
   i18n: {
@@ -296,29 +331,10 @@ const config = {
             activeBaseRegex: 'api/(1.19|1.20|1.21|1.22|1.23|next)/',
           },
           {
+            to: '/runner/0.2.11/',
+            label: 'Runner',
             position: 'left',
-            label: 'Blog',
+            activeBaseRegex: 'runner/(0.2.11|next)/',
-            href: 'https://blog.gitea.com',
-            className: 'internal-href',
-            target: '_self',
-          },
-          {
-            type: 'custom-apiDropdown',
-            label: 'API Version',
-            position: 'right',
-            items: [
-              {to: '/api/next/', label: '1.23-dev' },
-              {to: '/api/1.23/', label: '1.23.0-rc0' },
-              {to: '/api/1.22/', label: '1.22.6' },
-              {to: '/api/1.21/', label: '1.21.11' },
-              {to: '/api/1.20/', label: '1.20.6' },
-              {to: '/api/1.19/', label: '1.19.4' },
-            ],
-          },
-          {
-            href: 'https://github.com/go-gitea/gitea',
-            label: 'Code',
-            position: 'left',
           },
           {
             position: 'left',
@@ -340,6 +356,32 @@ const config = {
             position: 'right',
             dropdownActiveClassDisabled: true,
           },
+          {
+            type: 'custom-Dropdown',
+            label: 'API Version',
+            position: 'right',
+            items: [
+              {to: '/api/next/', label: '1.24-dev' },
+              {to: '/api/1.23/', label: '1.23.0-rc0' },
+              {to: '/api/1.22/', label: '1.22.6' },
+              {to: '/api/1.21/', label: '1.21.11' },
+              {to: '/api/1.20/', label: '1.20.6' },
+              {to: '/api/1.19/', label: '1.19.4' },
+            ],
+            routerRgx: '\/api\/',
+            classNames: 'api-dropdown',
+          },
+          {
+            type: 'custom-Dropdown',
+            label: 'Runner Version',
+            position: 'right',
+            items: [
+              {to: '/runner/next/', label: 'development' },
+              {to: '/runner/0.2.11/', label: '0.2.11' },
+            ],
+            routerRgx: '\/runner\/',
+            classNames: 'runner-dropdown',
+          },
           {
             to: 'help/support',
             position: 'right',

runner/index.md

@@ -0,0 +1,104 @@
+---
+sidebar_position: 1
+slug: /
+---
+
+# What is Gitea Runner
+
+Act runner is a runner for Gitea based on [Gitea fork](https://gitea.com/gitea/act) of [act](https://github.com/nektos/act). This documentation is a copy of https://gitea.com/gitea/act_runner/src/branch/main/README.md . And it should be updated once that README changed.
+
+## Installation
+
+### Prerequisites
+
+Docker Engine Community version is required for docker mode. To install Docker CE, follow the official [install instructions](https://docs.docker.com/engine/install/).
+
+### Download pre-built binary
+
+Visit [here](https://dl.gitea.com/act_runner/) and download the right version for your platform.
+
+### Build from source
+
+```bash
+make build
+```
+
+### Build a docker image
+
+```bash
+make docker
+```
+
+### Register
+
+```bash
+./act_runner register
+```
+
+And you will be asked to input:
+
+1. Gitea instance URL, like `http://192.168.8.8:3000/`. You should use your gitea instance ROOT_URL as the instance argument
+ and you should not use `localhost` or `127.0.0.1` as instance IP;
+2. Runner token, you can get it from `http://192.168.8.8:3000/admin/actions/runners`;
+3. Runner name, you can just leave it blank;
+4. Runner labels, you can just leave it blank.
+
+The process looks like:
+
+```text
+INFO Registering runner, arch=amd64, os=darwin, version=0.1.5.
+WARN Runner in user-mode.
+INFO Enter the Gitea instance URL (for example, https://gitea.com/):
+http://192.168.8.8:3000/
+INFO Enter the runner token:
+fe884e8027dc292970d4e0303fe82b14xxxxxxxx
+INFO Enter the runner name (if set empty, use hostname: Test.local):
+
+INFO Enter the runner labels, leave blank to use the default labels (comma-separated, for example, ubuntu-latest:docker://gitea/runner-images:ubuntu-latest):
+
+INFO Registering runner, name=Test.local, instance=http://192.168.8.8:3000/, labels=[ubuntu-latest:docker://gitea/runner-images:ubuntu-latest ubuntu-22.04:docker://gitea/runner-images:ubuntu-22.04 ubuntu-20.04:docker://gitea/runner-images:ubuntu-20.04].
+DEBU Successfully pinged the Gitea instance server
+INFO Runner registered successfully.
+```
+
+You can also register with command line arguments.
+
+```bash
+./act_runner register --instance http://192.168.8.8:3000 --token <my_runner_token> --no-interactive
+```
+
+If the registry succeed, it will run immediately. Next time, you could run the runner directly.
+
+### Run
+
+```bash
+./act_runner daemon
+```
+
+### Run with docker
+
+```bash
+docker run -e GITEA_INSTANCE_URL=https://your_gitea.com -e GITEA_RUNNER_REGISTRATION_TOKEN=<your_token> -v /var/run/docker.sock:/var/run/docker.sock --name my_runner gitea/act_runner:nightly
+```
+
+### Configuration
+
+You can also configure the runner with a configuration file.
+The configuration file is a YAML file, you can generate a sample configuration file with `./act_runner generate-config`.
+
+```bash
+./act_runner generate-config > config.yaml
+```
+
+You can specify the configuration file path with `-c`/`--config` argument.
+
+```bash
+./act_runner -c config.yaml register # register with config file
+./act_runner -c config.yaml daemon # run with config file
+```
+
+You can read the latest version of the configuration file online at [config.example.yaml](internal/pkg/config/config.example.yaml).
+
+### Example Deployments
+
+Check out the [examples](https://gitea.com/gitea/act_runner/src/branch/main/examples) directory for sample deployment types.

runner_versioned_docs/version-0.2.11/index.md

@@ -0,0 +1,104 @@
+---
+sidebar_position: 1
+slug: /
+---
+
+# What is Gitea Runner
+
+Act runner is a runner for Gitea based on [Gitea fork](https://gitea.com/gitea/act) of [act](https://github.com/nektos/act). This documentation is a copy of https://gitea.com/gitea/act_runner/src/branch/main/README.md . And it should be updated once that README changed.
+
+## Installation
+
+### Prerequisites
+
+Docker Engine Community version is required for docker mode. To install Docker CE, follow the official [install instructions](https://docs.docker.com/engine/install/).
+
+### Download pre-built binary
+
+Visit [here](https://dl.gitea.com/act_runner/) and download the right version for your platform.
+
+### Build from source
+
+```bash
+make build
+```
+
+### Build a docker image
+
+```bash
+make docker
+```
+
+### Register
+
+```bash
+./act_runner register
+```
+
+And you will be asked to input:
+
+1. Gitea instance URL, like `http://192.168.8.8:3000/`. You should use your gitea instance ROOT_URL as the instance argument
+ and you should not use `localhost` or `127.0.0.1` as instance IP;
+2. Runner token, you can get it from `http://192.168.8.8:3000/admin/actions/runners`;
+3. Runner name, you can just leave it blank;
+4. Runner labels, you can just leave it blank.
+
+The process looks like:
+
+```text
+INFO Registering runner, arch=amd64, os=darwin, version=0.1.5.
+WARN Runner in user-mode.
+INFO Enter the Gitea instance URL (for example, https://gitea.com/):
+http://192.168.8.8:3000/
+INFO Enter the runner token:
+fe884e8027dc292970d4e0303fe82b14xxxxxxxx
+INFO Enter the runner name (if set empty, use hostname: Test.local):
+
+INFO Enter the runner labels, leave blank to use the default labels (comma-separated, for example, ubuntu-latest:docker://gitea/runner-images:ubuntu-latest):
+
+INFO Registering runner, name=Test.local, instance=http://192.168.8.8:3000/, labels=[ubuntu-latest:docker://gitea/runner-images:ubuntu-latest ubuntu-22.04:docker://gitea/runner-images:ubuntu-22.04 ubuntu-20.04:docker://gitea/runner-images:ubuntu-20.04].
+DEBU Successfully pinged the Gitea instance server
+INFO Runner registered successfully.
+```
+
+You can also register with command line arguments.
+
+```bash
+./act_runner register --instance http://192.168.8.8:3000 --token <my_runner_token> --no-interactive
+```
+
+If the registry succeed, it will run immediately. Next time, you could run the runner directly.
+
+### Run
+
+```bash
+./act_runner daemon
+```
+
+### Run with docker
+
+```bash
+docker run -e GITEA_INSTANCE_URL=https://your_gitea.com -e GITEA_RUNNER_REGISTRATION_TOKEN=<your_token> -v /var/run/docker.sock:/var/run/docker.sock --name my_runner gitea/act_runner:nightly
+```
+
+### Configuration
+
+You can also configure the runner with a configuration file.
+The configuration file is a YAML file, you can generate a sample configuration file with `./act_runner generate-config`.
+
+```bash
+./act_runner generate-config > config.yaml
+```
+
+You can specify the configuration file path with `-c`/`--config` argument.
+
+```bash
+./act_runner -c config.yaml register # register with config file
+./act_runner -c config.yaml daemon # run with config file
+```
+
+You can read the latest version of the configuration file online at [config.example.yaml](internal/pkg/config/config.example.yaml).
+
+### Example Deployments
+
+Check out the [examples](https://gitea.com/gitea/act_runner/src/branch/main/examples) directory for sample deployment types.

runner_versions.json

@@ -0,0 +1,3 @@
+[
+    "0.2.11"
+]

src/components/APIDropDown.js

@@ -1,23 +0,0 @@
-import React from 'react';
-import DropdownNavbarItem from '@theme/NavbarItem/DropdownNavbarItem';
-import {useLocation} from '@docusaurus/router';
-
-export default function APIDropDown(props) {
-  const {pathname} = useLocation();
-  let newLabel = props.label;
-  // isAPI indicates if the current page is a api page
-  let isAPI = false;
-  for (const item of props.items) {
-    // paths like /zh-cn/api/{version}/ are also api pages
-    if (pathname === item.to || pathname === `/zh-cn${item.to}`) {
-      if (!props.mobile) newLabel = item.label;
-      isAPI = true;
-      break;
-    }
-  }
-  const newProps = {...props, label: newLabel};
-  // Hide api dropdown on non api pages
-  return (
-    <DropdownNavbarItem {...newProps} className={`api-dropdown${isAPI? '': ' gt-hidden'}`}></DropdownNavbarItem>
-  );
-}

src/components/DropDown.js

@@ -0,0 +1,18 @@
+import React from 'react';
+import DropdownNavbarItem from '@theme/NavbarItem/DropdownNavbarItem';
+import {useLocation} from '@docusaurus/router';
+
+export default function DropDown(props) {
+  const {pathname} = useLocation();
+  const {routerRgx, classNames} = props;
+  const r = new RegExp(routerRgx);
+  let isMatched = r.test(pathname);
+  let newLabel = props.label;
+  if (isMatched) {
+    newLabel = props.items.filter(item => item.to === pathname)[0]?.label ?? newLabel;
+  }
+  const newProps = {...props, label: newLabel};
+  return (
+    <DropdownNavbarItem {...newProps} className={`custom-dropdown ${classNames}${isMatched ? ' gt-visible': ' gt-hidden'}`}></DropdownNavbarItem>
+  );
+}

src/css/custom.css

@@ -131,6 +131,14 @@
     body:has(.redocusaurus) .navbar__item.dropdown:not(:has(.api-dropdown)) {
       display: none;
     }
+    /* hide other dropdowns except for runner dropdown on runner pages */
+    body:has(.runner-dropdown.gt-visible) .navbar__item.dropdown:not(:has(.runner-dropdown)) {
+      display: none;
+    }
+    /* hide dropdown menus that have sub-elements containing 'gt-hidden' */
+    body .navbar__item.dropdown:has(.custom-dropdown.gt-hidden) {
+      display: none;
+    }
   }
 
   @media (max-width: 996px) {
@@ -139,6 +147,14 @@
     body:has(.redocusaurus) .menu__list-item.menu__list-item--collapsed:not(:has(.api-dropdown)) {
       display: none;
     }
+    /* Hide collapsible menus except for Runner menu on Runner pages */
+    body:has(.runner-dropdown.gt-visible) .menu__list-item.menu__list-item--collapsed:not(:has(.runner-dropdown)) {
+      display: none;
+    }
+    /* Hide dropdown menus that have sub-elements containing 'gt-hidden' */
+    body .menu__list-item.menu__list-item--collapsed:has(.custom-dropdown.gt-hidden) {
+      display: none;
+    }
   }
 }
 /* selectors like :first-of-type are for browsers those do not support :has */

src/theme/NavbarItem/ComponentTypes.js

@@ -7,7 +7,7 @@ import DocNavbarItem from '@theme/NavbarItem/DocNavbarItem';
 import DocSidebarNavbarItem from '@theme/NavbarItem/DocSidebarNavbarItem';
 import DocsVersionNavbarItem from '@theme/NavbarItem/DocsVersionNavbarItem';
 import DocsVersionDropdownNavbarItem from '@theme/NavbarItem/DocsVersionDropdownNavbarItem';
-import APIDropDown from '@site/src/components/APIDropDown';
+import DropDown from '@site/src/components/DropDown';
 
 const ComponentTypes = {
   default: DefaultNavbarItem,
@@ -19,6 +19,6 @@ const ComponentTypes = {
   docSidebar: DocSidebarNavbarItem,
   docsVersion: DocsVersionNavbarItem,
   docsVersionDropdown: DocsVersionDropdownNavbarItem,
-  'custom-apiDropdown': APIDropDown,
+  'custom-Dropdown': DropDown,
 };
 export default ComponentTypes;