diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 00000000000..0f73e3e58b6 --- /dev/null +++ b/.github/workflows/docs.yml @@ -0,0 +1,43 @@ +name: Deploy Cloud Manager Docs + +on: + push: + branches: [develop] + +permissions: + pages: write + id-token: write + +jobs: + build: + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v3 + + - name: Setup Pages + uses: actions/configure-pages@v3 + + - uses: oven-sh/setup-bun@v1 + with: + bun-version: 1.0.21 + + - name: Build with VitePress + run: bunx vitepress@1.0.0-rc.35 build docs + + - name: Upload artifact + uses: actions/upload-pages-artifact@v2 + with: + path: docs/.vitepress/dist + + deploy: + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + needs: build + runs-on: ubuntu-latest + name: Deploy + steps: + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v2 \ No newline at end of file diff --git a/.gitignore b/.gitignore index 6a18d4bdabc..933adffc825 100644 --- a/.gitignore +++ b/.gitignore @@ -139,3 +139,6 @@ nohup.out packages/manager/bundle_analyzer_report.html **/manager/src/dev-tools/*.local.* + +# vitepress +docs/.vitepress/cache \ No newline at end of file diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts new file mode 100644 index 00000000000..282a8016c1d --- /dev/null +++ b/docs/.vitepress/config.ts @@ -0,0 +1,29 @@ +import { guides } from "./plugins/sidebar"; + +export default { + title: "Cloud Manager Docs", + description: "Akamai Cloud Manger Documentation", + srcDir: "./", + base: "/manager/", + themeConfig: { + logo: "/akamai-wave.svg", + nav: [ + { text: "Home", link: "/" }, + { text: "Getting Started", link: "/GETTING_STARTED" }, + { text: "Contributing", link: "/CONTRIBUTING" }, + ], + search: { + provider: "local", + }, + sidebar: [ + { + text: "Development Guide", + items: guides, + }, + ], + socialLinks: [ + { icon: "github", link: "https://github.com/linode/manager" }, + ], + }, + head: [["link", { rel: "icon", href: "/manager/favicon.ico" }]], +}; diff --git a/docs/.vitepress/plugins/sidebar.ts b/docs/.vitepress/plugins/sidebar.ts new file mode 100644 index 00000000000..94152e87047 --- /dev/null +++ b/docs/.vitepress/plugins/sidebar.ts @@ -0,0 +1,38 @@ +import * as fs from "fs"; +import * as path from "path"; + +const DEVELOPMENT_GUIDE_PATH = "./docs/development-guide"; + +interface MarkdownInfo { + text: string; + link: string; +} + +/** + * Aggregates the pages in the development-guide and populates the left sidebar. + */ +const scanDirectory = (directoryPath: string): MarkdownInfo[] => { + const markdownFiles = fs + .readdirSync(directoryPath) + .filter((file) => file.endsWith(".md")); + const markdownInfoArray: MarkdownInfo[] = []; + + markdownFiles.forEach((file) => { + const filePath = path.join(directoryPath, file); + const fileContent = fs.readFileSync(filePath, "utf-8"); + + const titleMatch = fileContent.match(/^#\s+(.*)/m); + const title = titleMatch ? titleMatch[1] : "Untitled"; + + const markdownInfo: MarkdownInfo = { + text: title, + link: `/development-guide/${file}`, + }; + + markdownInfoArray.push(markdownInfo); + }); + + return markdownInfoArray; +}; + +export const guides = scanDirectory(DEVELOPMENT_GUIDE_PATH); diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index 92f1030604a..1d3cf06f7aa 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -38,3 +38,7 @@ Feel free to open an issue to report a bug or request a feature. `Added`, `Fixed`, `Changed`, `Removed`, `Tech Stories`, `Tests`, `Upcoming Features` Two reviews from members of the Cloud Manager team are required before merge. After approval, all pull requests are squash merged. + +## Docs + +To run the docs development server locally, [install Bun](https://bun.sh/) and start the server: `yarn docs`. diff --git a/docs/GETTING_STARTED.md b/docs/GETTING_STARTED.md index 0b09c94ba73..f005663f28e 100644 --- a/docs/GETTING_STARTED.md +++ b/docs/GETTING_STARTED.md @@ -40,7 +40,7 @@ ``` 10. Navigate to the root directory of the repository, then start Cloud Manager and the JS client with `yarn up`. -11. After installation, Cloud Manager should be running at http://localhost:3000. +11. After installation, Cloud Manager should be running at `http://localhost:3000`. ## Serving a production build of Cloud Manager @@ -63,4 +63,4 @@ expose the Vite dev server, you can use the following command. ```bash yarn up:expose -``` \ No newline at end of file +``` diff --git a/docs/development-guide/08-testing.md b/docs/development-guide/08-testing.md index 5f817f1f662..91df0ddcad1 100644 --- a/docs/development-guide/08-testing.md +++ b/docs/development-guide/08-testing.md @@ -142,7 +142,7 @@ const { getByTestId } = renderWithTheme(, { #### Mocking with Mock Service Worker -We support mocking API requests both in test suites and the browser using the [msw](https://www.npmjs.com/package/msw) library. See [07-mocking-data](07-mocking-data.md) for more details. +We support mocking API requests both in test suites and the browser using the [msw](https://www.npmjs.com/package/msw) library. See [09-mocking-data](09-mocking-data.md) for more details. These mocks are automatically enabled for tests (using `beforeAll` and `afterAll` in src/setupTests.ts, which is run when setting up the Vitest environment). diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 00000000000..4330146c382 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,15 @@ +# Akamai Cloud Manager Documentation + +## Get Started + +To setup Cloud Manager and get ready for development, process to the [get started docs](GETTING_STARTED.md). + +## Contributing + +If you already have your development environment set up, please read the [contributing guidelines](CONTRIBUTING.md) to get help in creating your first Pull Request. + +To report a bug or request a feature in Cloud Manager, please [open a GitHub Issue](https://github.com/linode/manager/issues/new). For general feedback, use [linode.com/feedback](https://www.linode.com/feedback/). + +## Development Guide + +Please consult our [development guide](development-guide/01-repository-structure.md) to start contributing! diff --git a/docs/public/akamai-wave.svg b/docs/public/akamai-wave.svg new file mode 100644 index 00000000000..ecc82648017 --- /dev/null +++ b/docs/public/akamai-wave.svg @@ -0,0 +1,9 @@ + + + Shape + + + + + + \ No newline at end of file diff --git a/docs/public/favicon.ico b/docs/public/favicon.ico new file mode 100644 index 00000000000..f2c712fdba4 Binary files /dev/null and b/docs/public/favicon.ico differ diff --git a/package.json b/package.json index a4be2aceb0f..6abe225524a 100644 --- a/package.json +++ b/package.json @@ -43,7 +43,8 @@ "changeset": "node scripts/changelog/changeset.mjs", "generate-changelogs": "node scripts/changelog/generate-changelogs.mjs", "coverage": "yarn workspace linode-manager coverage", - "coverage:summary": "yarn workspace linode-manager coverage:summary" + "coverage:summary": "yarn workspace linode-manager coverage:summary", + "docs": "bunx vitepress@1.0.0-rc.35 dev docs" }, "resolutions": { "minimist": "^1.2.3", diff --git a/packages/manager/.changeset/pr-10027-added-1704309699899.md b/packages/manager/.changeset/pr-10027-added-1704309699899.md new file mode 100644 index 00000000000..768d2b13bbf --- /dev/null +++ b/packages/manager/.changeset/pr-10027-added-1704309699899.md @@ -0,0 +1,5 @@ +--- +"@linode/manager": Added +--- + +Cloud Manager Documentation microsite with vitepress ([#10027](https://github.com/linode/manager/pull/10027))