POC: [M3-7538] - Cloud Manager GH Pages Docs #9960

abailly-akamai · 2023-12-05T18:33:21Z

Description 📝

This PR is a rather quick attempt at configuring a basic Jekyll site builder for our docs and publish it automatically when pushed to a branch of our choice (in this case M3-7538, hence why this branch isn't from my fork.

The advantage of this approach is to integrate things easily with very minimal dependencies and get dedicated hosting for the static site. It could be done in many ways via other static builders (hugo etc) but I don't think we need to go too far at the moment since this is very much a built in, secure solution we can just use almost out of the box.

I also used a theme that had a lot of decent features (navigation, search, responsive design, easy to customize) to facilitate development and user experience. The search is really super useful! 🎉

The site is published at https://linode.github.io/manager

In this PR i did not update the main README to link to this doc site since it may not be ready for prime time but that can easily be done now or later, depending on feedback for the POC.

NOTE: some doc pages may have formatting issues (unrelated to this PR) which I will update if this PR moves forward.

Changes 🔄

Add builder and documentation to publish our documentation to GH pages

Preview 📷

How to test 🧪

Verification steps

Take a look at
Test local development (optional) with the help of https://github.com/linode/manager/blob/cfdfa81c60bdfaa8d1cc7045f577c1bcae3779c9/docs/README.md
Review docs and config

As an Author I have considered 🤔

Check all that apply

bnussman-akamai

Looks awesome! Love that we can use Github Pages for this!

Is the choice of Jekyll just because Github supports it without needing a dedicated Github Action to build and publish? I like how it's super built in, but the Gemfiles, html, and scss will definitely placebo me into feeling our repo is bloated and messy.

What do you think about using something more modern and applicable to our Typescript ecosystem like https://vitepress.dev. I'm not super familiar with Vitepress and how it compares to jekyll, but it does seem to be the standard for the Typescript ecosystem as of now. I guess a disadvantage would be that we need a Github Action with a build step and more node_modules?

github-actions · 2023-12-05T19:37:47Z

Coverage Report: ✅
Base Coverage: 85.39%
Current Coverage: 85.39%

mjac0bs

I'm a big fan of Github Pages, thanks for setting this up!

I've left some nitpicks on typos and wording that I found as I read through the docs. As far as the actual pages site, I think it looks nice. Good choice on theme; I love the search. My one complaint so far about layout is that the side menu seems really wide. Can we we adjust that? I was going to play with the theme overrides a bit to see what we've got. Either way, not a blocker.

mjac0bs · 2023-12-05T19:23:20Z

docs/README.md

+
+This doc builder uses default GitHub pages and its Jekyll site builder to deploy documentation pages to [https://linode.github.io/manager](https://linode.github.io/manager).
+
+It automatically get deployed when we release to `master`.


Suggested change

It automatically get deployed when we release to `master`.

It automatically gets deployed when we release to `master`.

mjac0bs · 2023-12-05T19:24:06Z

docs/README.md

+
+In order to develop locally, start by setting up your tolling locally by following the steps on this [page](https://docs.github.com/en/pages/setting-up-a-github-pages-site-with-jekyll/testing-your-github-pages-site-locally-with-jekyll).
+
+This should be done from the /docs/ directory.


Suggested change

This should be done from the /docs/ directory.

This should be done from the `/docs/` directory.

mjac0bs · 2023-12-05T19:24:13Z

docs/README.md

+- modify the styles by updating `_sass/color_schemes/akamai.scss`.
+- modify layouts by adding/updating HTML templates to the `_includes` directory.
+
+See [https://just-the-docs.com/docs/customization](https://just-the-docs.com/docs/customization) for mor info.


Suggested change

See [https://just-the-docs.com/docs/customization](https://just-the-docs.com/docs/customization) for mor info.

See [https://just-the-docs.com/docs/customization](https://just-the-docs.com/docs/customization) for more info.

mjac0bs · 2023-12-05T19:32:34Z

packages/manager/.changeset/pr-9960-added-1701803707300.md

+"@linode/manager": Added
+---
+
+Cloud Manager Documenation Builder for Gihub Pages ([#9960](https://github.com/linode/manager/pull/9960))


Suggested change

Cloud Manager Documenation Builder for Gihub Pages ([#9960](https://github.com/linode/manager/pull/9960))

Cloud Manager Documentation Builder for Github Pages ([#9960](https://github.com/linode/manager/pull/9960))

mjac0bs · 2023-12-05T19:33:26Z

docs/index.md

+
+## Get Started
+
+To setup cloud manager and get ready for development, process to the [get started docs](GETTING_STARTED.md).


Suggested change

To setup cloud manager and get ready for development, process to the [get started docs](GETTING_STARTED.md).

To setup Cloud Manager and get ready for development, proceed to the [getting started docs](GETTING_STARTED.md).

mjac0bs · 2023-12-05T19:35:31Z

docs/development-guide/index.md

+
+Find resources about specific areas of development in Akamai's Cloud Manager.
+
+For any other issues feel free to open an issue to report a bug or request a feature.


Suggested change

For any other issues feel free to open an issue to report a bug or request a feature.

For any other issues, feel free to [open a GitHub Issue](https://github.com/linode/manager/issues/new) to report a bug or request a feature.

abailly-akamai · 2023-12-05T20:02:49Z

@bnussman-akamai I was waiting for this comment 😄 yes, it is what GH pages using under the hood.

The perception that the repo is "bloated" is quite subjective and personal, and I'd like to make the debate more objective. The quest for a 100% TS repo does not convey much to me. I actually like the idea of diversifying the tech and focus on the right tool for the job. In other words I don't really care that much what brand is the guitar, I care about the music it makes 🎵.

That being I am open to other options (I am sure Vitpress is fine and is a proper tool for it) but it seems overkill to me to spend a lot more time to achieve the exact same (or similar) result? This was build in half a day so there is that.
We can certainly go another route but I'd like to hear more compelling arguments for it. One i can think of is having to install more tooling to your machine if you want to develop this locally.

Curious to hear other opinions as well.

tyler-akamai · 2023-12-11T14:54:31Z

docs/development-guide/index.md

+
+# Development Guide
+
+Find resources about specific areas of development in Akamai's Cloud Manager.


Do you mean the documentation? If so should we point them here https://www.linode.com/docs/?

tyler-akamai · 2023-12-11T15:02:39Z

Curious to hear other opinions as well.

I think both solutions are valid. But given that this was an easy and fast setup and it does everything we want right now, my vote is to keep it. In the future, if we want more features, it seems like vitepress is a good option. And we wouldnt have to tear down much to make the transition.

tyler-akamai · 2023-12-11T16:04:05Z

Also, might be worth adding POC to the list of potential tickets types in the PR template

jcallahan-akamai · 2023-12-12T16:54:09Z

@bnussman-akamai I was waiting for this comment 😄 yes, it is what GH pages using under the hood.

The perception that the repo is "bloated" is quite subjective and personal, and I'd like to make the debate more objective. The quest for a 100% TS repo does not convey much to me. I actually like the idea of diversifying the tech and focus on the right tool for the job. In other words I don't really care that much what brand is the guitar, I care about the music it makes 🎵.

That being I am open to other options (I am sure Vitpress is fine and is a proper tool for it) but it seems overkill to me to spend a lot more time to achieve the exact same (or similar) result? This was build in half a day so there is that. We can certainly go another route but I'd like to hear more compelling arguments for it. One i can think of is having to install more tooling to your machine if you want to develop this locally.

Curious to hear other opinions as well.

I agree having a 100% TS repo doesn't mean much on its own, but one factor to consider is the skillset of the team and whether or not we are in a position to support this little slice of Ruby. @abailly-akamai do you have a sense for the likelihood of ever having to run/debug this locally? Maybe a good cafe topic to see if we have Ruby skills on the team (and/or interest in learning).

abailly-akamai · 2023-12-12T17:09:09Z

@johnwcallahan yup am planning to bring this to the cafe. I don't feel that strong about it, but i also think that apart from installing tools and dependencies the ruby factor is a tad irrelevant cause it's just supporting a compiler in this case. With a bit of work we could probably move this to a GH action as well and remove this from the codebase. I wrote steps to run this locally as part of this PR but let's remember this is POC, showing what the end result is, we can find ways to clean it up - what I want to be cautious about is jump on the latest coolest JS framework bandwagon that's going to require pouring gallons of JS to build < 20 pages of docs.

carrillo-erik · 2023-12-13T17:45:51Z

docs/README.md

+
+## Local Development
+
+In order to develop locally, start by setting up your tolling locally by following the steps on this [page](https://docs.github.com/en/pages/setting-up-a-github-pages-site-with-jekyll/testing-your-github-pages-site-locally-with-jekyll).


I think you meant "tooling" instead of "tolling".

carrillo-erik · 2023-12-13T18:03:39Z

This is a great idea! Upon initial review of the UI/UX I have the following recommendations:

Add dark theme.
Add borders and/or background color to Search Bar.
Improve desktop page layout (too much empty space).

abailly-akamai added 9 commits December 4, 2023 16:42

Add index file

0e4ec93

Include contributing and theme pick

3adcc20

uppercase

525f118

include as array

27422ad

Basic theming

d62010a

cleanup and theme config

422d67e

cleanup and theme config

b365a53

cleanup and theme config

b2b9129

Trying remote theme

f485535

abailly-akamai self-assigned this Dec 5, 2023

Add development doc

cfdfa81

abailly-akamai temporarily deployed to github-pages December 5, 2023 19:04 — with GitHub Pages Inactive

abailly-akamai marked this pull request as ready for review December 5, 2023 19:13

abailly-akamai requested a review from a team as a code owner December 5, 2023 19:13

abailly-akamai requested review from carrillo-erik, tyler-akamai, jcallahan-akamai, bnussman-akamai and jdamore-linode and removed request for a team December 5, 2023 19:13

Add changeset

ccbadb7

abailly-akamai temporarily deployed to github-pages December 5, 2023 19:17 — with GitHub Pages Inactive

abailly-akamai requested a review from coliu-akamai December 5, 2023 19:20

bnussman-akamai reviewed Dec 5, 2023

View reviewed changes

mjac0bs reviewed Dec 5, 2023

View reviewed changes

abailly-akamai added the Proof of Concept label Dec 5, 2023

bnussman-akamai added the Documentation Improving / adding to our documentation label Dec 5, 2023

tyler-akamai reviewed Dec 11, 2023

View reviewed changes

tyler-akamai approved these changes Dec 11, 2023

View reviewed changes

carrillo-erik reviewed Dec 13, 2023

View reviewed changes

bnussman-akamai mentioned this pull request Dec 14, 2023

poc: Cloud Manager Github Pages Docs #10002

Closed

12 tasks

abailly-akamai closed this Jan 3, 2024

abailly-akamai mentioned this pull request Jan 3, 2024

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

Merged

12 tasks

bnussman-akamai deleted the M3-7538 branch January 18, 2024 14:09

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

POC: [M3-7538] - Cloud Manager GH Pages Docs #9960

POC: [M3-7538] - Cloud Manager GH Pages Docs #9960

abailly-akamai commented Dec 5, 2023 •

edited

Loading

bnussman-akamai left a comment •

edited

Loading

github-actions bot commented Dec 5, 2023

mjac0bs left a comment

mjac0bs Dec 5, 2023

mjac0bs Dec 5, 2023

mjac0bs Dec 5, 2023

mjac0bs Dec 5, 2023

mjac0bs Dec 5, 2023

mjac0bs Dec 5, 2023

abailly-akamai commented Dec 5, 2023

tyler-akamai Dec 11, 2023

tyler-akamai commented Dec 11, 2023 •

edited

Loading

tyler-akamai commented Dec 11, 2023 •

edited

Loading

jcallahan-akamai commented Dec 12, 2023

abailly-akamai commented Dec 12, 2023

carrillo-erik Dec 13, 2023

carrillo-erik commented Dec 13, 2023


		This doc builder uses default GitHub pages and its Jekyll site builder to deploy documentation pages to [https://linode.github.io/manager](https://linode.github.io/manager).

		It automatically get deployed when we release to `master`.

	It automatically get deployed when we release to `master`.
	It automatically gets deployed when we release to `master`.


		In order to develop locally, start by setting up your tolling locally by following the steps on this [page](https://docs.github.com/en/pages/setting-up-a-github-pages-site-with-jekyll/testing-your-github-pages-site-locally-with-jekyll).

		This should be done from the /docs/ directory.

	This should be done from the /docs/ directory.
	This should be done from the `/docs/` directory.

	See [https://just-the-docs.com/docs/customization](https://just-the-docs.com/docs/customization) for mor info.
	See [https://just-the-docs.com/docs/customization](https://just-the-docs.com/docs/customization) for more info.

	Cloud Manager Documenation Builder for Gihub Pages ([#9960](https://github.com/linode/manager/pull/9960))
	Cloud Manager Documentation Builder for Github Pages ([#9960](https://github.com/linode/manager/pull/9960))


		## Get Started

		To setup cloud manager and get ready for development, process to the [get started docs](GETTING_STARTED.md).


		Find resources about specific areas of development in Akamai's Cloud Manager.

		For any other issues feel free to open an issue to report a bug or request a feature.

	For any other issues feel free to open an issue to report a bug or request a feature.
	For any other issues, feel free to [open a GitHub Issue](https://github.com/linode/manager/issues/new) to report a bug or request a feature.


		# Development Guide

		Find resources about specific areas of development in Akamai's Cloud Manager.


		## Local Development

		In order to develop locally, start by setting up your tolling locally by following the steps on this [page](https://docs.github.com/en/pages/setting-up-a-github-pages-site-with-jekyll/testing-your-github-pages-site-locally-with-jekyll).

POC: [M3-7538] - Cloud Manager GH Pages Docs #9960

POC: [M3-7538] - Cloud Manager GH Pages Docs #9960

Conversation

abailly-akamai commented Dec 5, 2023 • edited Loading

Description 📝

Changes 🔄

Preview 📷

How to test 🧪

Verification steps

As an Author I have considered 🤔

bnussman-akamai left a comment • edited Loading

Choose a reason for hiding this comment

github-actions bot commented Dec 5, 2023

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

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

abailly-akamai commented Dec 5, 2023

Choose a reason for hiding this comment

tyler-akamai commented Dec 11, 2023 • edited Loading

tyler-akamai commented Dec 11, 2023 • edited Loading

jcallahan-akamai commented Dec 12, 2023

abailly-akamai commented Dec 12, 2023

Choose a reason for hiding this comment

carrillo-erik commented Dec 13, 2023

abailly-akamai commented Dec 5, 2023 •

edited

Loading

bnussman-akamai left a comment •

edited

Loading

tyler-akamai commented Dec 11, 2023 •

edited

Loading

tyler-akamai commented Dec 11, 2023 •

edited

Loading