feat: [M3-7538] - Cloud Manager Docs with Vitepress #10027

abailly-akamai · 2024-01-03T16:50:19Z

Description 📝

This is the latest iteration of a docsite generation for the Cloud Manager docs.

It iterates over the two previous POCs:

This version addresses the concerns of added dependencies to build the docs and utilizes the much better looking vitepress version. Instead of adding dev dependencies to the monorepo we utilize npx (more specifically its bun equivalent bunx) to get those on the fly during build time.

As a result there's 0 dependencies added to generate our docs 🎉
The same process is used to develop locally.

The pages will eventually live at https://linode.github.io/manager/ but until then the PR has been merged we can see the result at:
👉 https://abailly-akamai.github.io/manager/

Thanks @bnussman-akamai for the vitepress suggestion, GH action and @mjac0bs for the inspiration!

Note: We will need to also link to this documentation from the README and in other knowledge sources, tasks that will be done separately (we also need to clean/update the docs themselves)

Changes 🔄

Configure vitepress to build our docs automatically

Preview 📷

How to test 🧪

verify build steps: https://github.com/abailly-akamai/manager/actions/runs/7400941878
verify documentation quality: https://abailly-akamai.github.io/manager
locally, pull code and run yarn docs to get the local version

As an Author I have considered 🤔

Check all that apply

abailly-akamai · 2024-01-03T19:15:02Z

.github/workflows/docs.yml

+
+      - uses: oven-sh/setup-bun@v1
+        with:
+          bun-version: 1.0.21


pinning bun version for good measure

abailly-akamai · 2024-01-03T19:15:58Z

.github/workflows/docs.yml

+
+      - name: Build with VitePress
+        run: |
+          bunx vitepress@1.0.0-rc.35 build docs


pinning the vitepress version as well. We may want to update this when the major version comes out

abailly-akamai · 2024-01-03T19:19:13Z

docs/plugins/sidebar.ts

+  return markdownInfoArray;
+}
+
+export const guides = scanDirectory(DEVELOPMENT_GUIDE_PATH);


This is a pretty basic plugin to aggregate the pages in the development-guide and populate the left sidebar.

As discussed with @bnussman-akamai it is not super dynamic at the moment since it won't handle recursion or other directories, but it serves our purpose well considering the doc structure isn't something that's been updated (or will be updated) very soon. If it does it wouldn't be too hard to update top get there.

Can we include this info as a comment (as least: "Aggregates the pages in the development-guide and populates the left sidebar") in this file?

abailly-akamai · 2024-01-03T19:20:28Z

.github/workflows/docs.yml

+
+on:
+  push:
+    branches: [develop]


we may want to target master eventually? I think it's ok for now but open to feedback

My vote would be keeping develop with this setup. Our docs are mostly targeted at developers and we want them looking at our latest documentation at all times.

I also hold this opinion on Storybook but I don't think many agree

If we start building multiple environments (like design.dev.linode.com or docs.cloud.dev.linode.com) then it would be a different story imo

My vote would be keeping develop with this setup. Our docs are mostly targeted at developers and we want them looking at our latest documentation at all times.

I'd agree with this.

github-actions · 2024-01-03T19:42:56Z

Coverage Report: ✅
Base Coverage: 79.16%
Current Coverage: 79.16%

bnussman-akamai

Awesome 🎉 I'm happy with the outcome!

This will definitely make it more appealing to document (and consume documentation) for Cloud Manager

bnussman-akamai · 2024-01-03T19:27:48Z

.github/workflows/docs.yml

+
+on:
+  push:
+    branches: [develop]


My vote would be keeping develop with this setup. Our docs are mostly targeted at developers and we want them looking at our latest documentation at all times.

I also hold this opinion on Storybook but I don't think many agree

If we start building multiple environments (like design.dev.linode.com or docs.cloud.dev.linode.com) then it would be a different story imo

.github/workflows/docs.yml

package.json

docs/plugins/sidebar.ts

mjac0bs

Just a couple minor comments about documentation. This was looking good in the test deploy and running locally! 🎉

mjac0bs · 2024-01-03T20:36:53Z

.github/workflows/docs.yml

+
+on:
+  push:
+    branches: [develop]


My vote would be keeping develop with this setup. Our docs are mostly targeted at developers and we want them looking at our latest documentation at all times.

I'd agree with this.

package.json

docs/index.md

mjac0bs · 2024-01-03T20:56:46Z

docs/plugins/sidebar.ts

+  return markdownInfoArray;
+}
+
+export const guides = scanDirectory(DEVELOPMENT_GUIDE_PATH);


Can we include this info as a comment (as least: "Aggregates the pages in the development-guide and populates the left sidebar") in this file?

jdamore-linode

This is great, awesome work @abailly-akamai and @bnussman-akamai! Looking forward to sprucing up the testing docs once this is merged 🎉

What's the motivation behind using bunx over npx? I thought npx was a nice idea since it wouldn't require developers to install anything in addition to what we already require, and it's one more dependency we need support/document/maintain (similarly, I think we should also add a step in GETTING_STARTED.md to instruct the user to install Bun, and document which version(s) we support). Regardless, it is cool seeing Bun in action!

bnussman-akamai · 2024-01-04T18:26:15Z

@jdamore-linode I generally agree that npx would be nice to not introduce additional dependency. The only reason I'm okay with (and encouraged) bunx here is because I'm really hoping and betting on Bun replacing node for us in over the next few months/years. I figured this would be a nice low friction way to start integrating Bun into our workflow.

If we want to keep is simple and not take the bet on Bun yet, I'm fine with reverting to npx for this, I just really want Bun to work in the long run!

jdamore-linode · 2024-01-04T18:44:58Z

Thanks @bnussman-akamai, that makes sense to me! I'm happy (and excited) to give Bun a shot. Also just noticed the addition to CONTRIBUTING.md that mentions the Bun installation, so feel free to disregard what I said about GETTING_STARTED.md.

I just really want Bun to work in the long run!

Hear, hear!

cpathipa

Nice work @abailly-akamai!

abailly-akamai added 6 commits January 3, 2024 11:10

Initial commit - config

e2bb298

Add GHA

f76f706

cleanup

3d14d72

cleanup

f606118

clean comments

390c7c4

clean plugin

7282826

abailly-akamai changed the title ~~[M3-7538] Vitepress~~ [M3-7538] Cloud Manager Docs with Vitepress Jan 3, 2024

abailly-akamai self-assigned this Jan 3, 2024

remove setup node

c23e5a6

bnussman-akamai mentioned this pull request Jan 3, 2024

poc: Cloud Manager Github Pages Docs #10002

Closed

12 tasks

abailly-akamai added 2 commits January 3, 2024 12:57

replace npx with bunx

5866079

fix assets paths

5cadd67

abailly-akamai commented Jan 3, 2024

View reviewed changes

abailly-akamai marked this pull request as ready for review January 3, 2024 19:19

abailly-akamai requested a review from a team as a code owner January 3, 2024 19:19

abailly-akamai requested review from jdamore-linode and mjac0bs and removed request for a team January 3, 2024 19:19

abailly-akamai commented Jan 3, 2024

View reviewed changes

Added changeset: Cloud Manager Documentation microsite with vitepress

dea3b1d

abailly-akamai requested review from bnussman-akamai, jaalah-akamai and jcallahan-akamai January 3, 2024 19:22

fix typo

62d1f06

bnussman-akamai approved these changes Jan 3, 2024

View reviewed changes

bnussman-akamai changed the title ~~[M3-7538] Cloud Manager Docs with Vitepress~~ feat: [M3-7538] - Cloud Manager Docs with Vitepress Jan 3, 2024

mjac0bs approved these changes Jan 3, 2024

View reviewed changes

bnussman-akamai added Documentation Improving / adding to our documentation Approved Multiple approvals and ready to merge! labels Jan 3, 2024

abailly-akamai added 2 commits January 4, 2024 10:05

Feedback

3d97408

Feedback 2

5bb2fda

jdamore-linode approved these changes Jan 4, 2024

View reviewed changes

cpathipa approved these changes Jan 4, 2024

View reviewed changes

abailly-akamai merged commit cffed4f into linode:develop Jan 5, 2024
18 checks passed

This was referenced Jan 18, 2024

Release v1.110.0 - release → staging #10081

Closed

Release v1.110.0 - release → staging #10082

Merged

Release v1.110.0 - staging → master #10092

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: [M3-7538] - Cloud Manager Docs with Vitepress #10027

feat: [M3-7538] - Cloud Manager Docs with Vitepress #10027

abailly-akamai commented Jan 3, 2024 •

edited by bnussman-akamai

Loading

abailly-akamai Jan 3, 2024

abailly-akamai Jan 3, 2024

abailly-akamai Jan 3, 2024

mjac0bs Jan 3, 2024

abailly-akamai Jan 3, 2024

bnussman-akamai Jan 3, 2024

mjac0bs Jan 3, 2024

github-actions bot commented Jan 3, 2024 •

edited

Loading

bnussman-akamai left a comment

bnussman-akamai Jan 3, 2024

mjac0bs left a comment

mjac0bs Jan 3, 2024

mjac0bs Jan 3, 2024

jdamore-linode left a comment

bnussman-akamai commented Jan 4, 2024 •

edited

Loading

jdamore-linode commented Jan 4, 2024

cpathipa left a comment

feat: [M3-7538] - Cloud Manager Docs with Vitepress #10027

feat: [M3-7538] - Cloud Manager Docs with Vitepress #10027

Conversation

abailly-akamai commented Jan 3, 2024 • edited by bnussman-akamai Loading

Description 📝

Changes 🔄

Preview 📷

How to test 🧪

As an Author I have considered 🤔

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

github-actions bot commented Jan 3, 2024 • edited Loading

bnussman-akamai left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mjac0bs left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jdamore-linode left a comment

Choose a reason for hiding this comment

bnussman-akamai commented Jan 4, 2024 • edited Loading

jdamore-linode commented Jan 4, 2024

cpathipa left a comment

Choose a reason for hiding this comment

abailly-akamai commented Jan 3, 2024 •

edited by bnussman-akamai

Loading

github-actions bot commented Jan 3, 2024 •

edited

Loading

bnussman-akamai commented Jan 4, 2024 •

edited

Loading