From cffed4f9a0106511103ee712c1531bd32df97d5a Mon Sep 17 00:00:00 2001 From: Alban Bailly <130582365+abailly-akamai@users.noreply.github.com> Date: Fri, 5 Jan 2024 09:53:18 -0500 Subject: [PATCH] feat: [M3-7538] - Cloud Manager Docs with Vitepress (#10027) * Initial commit - config * Add GHA * cleanup * cleanup * clean comments * clean plugin * remove setup node * replace npx with bunx * fix assets paths * Added changeset: Cloud Manager Documentation microsite with vitepress * fix typo * Feedback * Feedback 2 --- .github/workflows/docs.yml | 43 ++++++++++++++++++ .gitignore | 3 ++ docs/.vitepress/config.ts | 29 ++++++++++++ docs/.vitepress/plugins/sidebar.ts | 38 ++++++++++++++++ docs/CONTRIBUTING.md | 4 ++ docs/GETTING_STARTED.md | 4 +- docs/development-guide/08-testing.md | 2 +- docs/index.md | 15 ++++++ docs/public/akamai-wave.svg | 9 ++++ docs/public/favicon.ico | Bin 0 -> 16958 bytes package.json | 3 +- .../pr-10027-added-1704309699899.md | 5 ++ 12 files changed, 151 insertions(+), 4 deletions(-) create mode 100644 .github/workflows/docs.yml create mode 100644 docs/.vitepress/config.ts create mode 100644 docs/.vitepress/plugins/sidebar.ts create mode 100644 docs/index.md create mode 100644 docs/public/akamai-wave.svg create mode 100644 docs/public/favicon.ico create mode 100644 packages/manager/.changeset/pr-10027-added-1704309699899.md 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 0000000000000000000000000000000000000000..f2c712fdba4fd4e394f91f7eb8e80de2be06d3cd GIT binary patch literal 16958 zcmdskMS<;87oGE%yi%cz2Fj>~r`cMXvy^uH`G&2;; zGDE|n5Gp7VlL&j6QhFgl3(Sm&%`Kx+nzCr9X>Y%0=AO&(diUNl)83=kmH$5Hp7Xr@ z&pC7Mxo7U`I2ryG3J$-|cg9@nIA=SKGX_xQ6oJ&&erOv!ppJUQiTS;MgEJ6}2a~|< z;4ZKfbe@=ul8p+lAz(Im2J8YyfE$9H$!22DJKS2qo#2BIo;vsMXkQL4wU=FTk>DX? zy%rn=I?rJFW7?-Cmx*1^a2WtrgDMDe)vx!_KFMx&$wq_EEbvzh?|*1tm~19?y~C$J z*dD`M#$MLEVRo}iHX3{;fWtta+hOHZ$!22TJDhJb;4OVI$9{InMugJ>L+&>vn~8nz z@SbPLeTx0;l8p%OX@=ZS#W_C??s4~Z`Mj@4b`9G0Zw@X?lK2X)#uhv4EVoicU0^|gSY8@zF;RKyHVhOz+miOx0{unXz;$n zfV+I|Pq}@L^f0_WG~mD6&S=<;0&h8&)bH!Pl^5I1%uY18KWxZ&?sDR$)ysCdf=ZC(W`=xsSOa8LYp9&PmC^>cQQ!eX z{-YIt&rbSky{b#2B>x-1W)L;*(sl^6DUOuYK5@0GOQZC7yn~G6zeneX{wB{R)zAKL zcogjQxJ32AjsXANp3PdlK5b<<$Qu5w0sk$E8@lqH&(EICR#l%y35O@aL61w+_`jg| zp*sS|_d25gg{n`ZB>!gkkM+0_7jYzb(Y(q zoKMJmH-CdcQF+iF_r8{J^v^#iUjr0xUCxb)W223{WUepM@{4`P4Bdv#ztBGobZaqG zAN)q$xi)wPV-R-`koPIeK;?6NP%rEn{f5s!v3W|1qvDA??o5cf#b8NT?Eh1T&n&nB zYynlE=P|hv-`JJ{_PQ@s_Rqi3ofx6NPLGY=6+q^O_}Kt12dC>gre*9#gH9lv4+E8( zlJaae-qfGc!^ZUckDE1{H$vj8JeDdwCDDCO)0bz5_kp}0y9CSuw}R_{jOh%}0pznO zI&XtRK=}`oFVo&szedbuxH9_dJv+rU zOv?N_Px+#}!oWuS$eKMLWRz`RO8kxm^0`nsuW80V_IorR%2!YZ&qZG{uu(o_Uatig zH=F11O9a1s(j3xM*md<8)d8HL2Nbx;UIhKkzgQb z0kYQ=*#_j^A$d&(cY|laUZDKw@<-}JpLtC9iw^eFdhxBtk#dLblj{wJc0oVt`d{pi z0O^vF1_XWW| z7=!Is7W-jiSpI!c2M5#l-#dfxuG+v5Mu%ed*%qv)8oDu#jZbC1cGO0 zLEA>IW$l|4?C&J6iPs9Yg19_)p%c3PQZIi4xen|Daenl6Srp;J%K3viXDK89?^#1uzqIfW<)8wthDAbzQfT;}<{0x~w|wwac+;k~ZO53oo|%$8PQKRO;~*>T zz4ABO!59aggUA6~#{J6yt zPR=d2yT#hqH0^GwcHEJ7yRt?6EOX15691zEp`5b#!{I{?7B1uB)cUlT>yniGaZ}@{ N#?>v>8Mzga{{fCcRWkqp literal 0 HcmV?d00001 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))