[docs] render the documentation as a website #1840

flynnduism · 2020-10-14T22:26:07Z

This PR renders the content of the /docs dir as a hugo static website, deployed via Netlify.
Preview url: https://osm-docs.netlify.app/

There are a few WIP pieces to be added to this, either here or in subsequent PRs...

theme adjustments (@flynnduism)
docs content structuring (@phillipgibson)

shashankram · 2020-10-14T22:30:16Z

@flynnduism looks great, would you mind rebasing.

flynnduism · 2020-10-15T20:11:28Z

@shashankram will do - I'll update this PR to omit any changes to the docs markdown files, to avoid these conflicts.

flynnduism · 2020-10-19T23:21:04Z

Working on these dos:

add a Readme for the website
include versioning menu (as per these steps)
rebase this PR to avoid conflicts of docs/content/

flynnduism · 2020-10-27T19:00:31Z

This is ready for review @phillipgibson

added a website Readme with all of the website info and notes
included release versioning for the project. process notes included in the Readme
resolved conflicts, freshly rebased

I'd recommend this PR be followed up with edits to the current documentation files at docs/*.md, to review how they're organized, and cross-linked and to review their metadata to work in this new format.

codecov-io · 2020-10-27T19:35:47Z

Codecov Report

Merging #1840 into main will increase coverage by 0.01%.
The diff coverage is n/a.

@@            Coverage Diff             @@
##             main    #1840      +/-   ##
==========================================
+ Coverage   56.55%   56.57%   +0.01%     
==========================================
  Files         140      140              
  Lines        5644     5644              
==========================================
+ Hits         3192     3193       +1     
+ Misses       2449     2448       -1     
  Partials        3        3

Impacted Files	Coverage Δ
pkg/envoy/route/config.go	`96.03% <0.00%> (+0.79%)`	⬆️

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 5988b66...368ef1b. Read the comment docs.

flynnduism · 2020-10-27T21:23:23Z

The addition of the Netlify bot was causing OSM pull requests to fail. #1930

This is disabled for now. If this PR is merged in, I can reactivate the integration afterwards with some limitations to avoid these issues reappearing.

Steps to reactivate Netlify integration (for auto deploys, and generating previews of pull requests)

Netlify Github App needs to be re-added to the repo
Build & Deploy is stopped
Pull Request notifications (checks) have all been removed from the Netlify config

bridgetkromhout · 2020-11-03T20:46:27Z

docs/content/_index.md

+
+![OSM Install Demo](https://github.com/openservicemesh/osm/raw/main/img/osm-install-demo-v0.2.0.gif "OSM Install Demo")
+
+See the [installation guide](docs/installation_guide.md) for more detailed options.


This link doesn't work in the preview and it seems like it wouldn't work in general - assuming this is being generated from the code repo, do we need to change it to a fully qualified URL so it can work from here?

Removed this link for now so that a broken link is not introduced.

I'd like to keep this PR focused on generating the website (config and theme) and have content edits to the docs be added separately via follow up PRs & Issues. Discussed with @phillipgibson, there are edits that should happen and I think those are best handled by the OSM team, before this website be made accessible to the public.

Recommended follow-up edits:

Create a proper landing page - the current index.md page referenced here is temporary (copied from the OSM readme), a tailored Docs welcome / intro is needed to best guide project users

Content needs to be reorganized - right now only 1 file exists in the docs/content site dir. The content should be reviewed and moved into the required structure, grouped into subsections as needed *

Review metadata - the existing docs need Hugo frontmatter added to render properly for the web *

I had carried out some of this work via this PR, but it was problematic as this PR is already large without any docs files edits - there were a lot of rebase conflicts from other changes in flight. This PR would in turn then cause a lot of other rebase headaches for other open PRs. Hence, I removed those edits and reduced the size of this PR.

* The website README that is introduced in this PR provides further details on the ideal structure and the necessary front matter metadata that should be used.

Signed-off-by: flynnduism <dev@ronan.design>

Signed-off-by: flynnduism <dev@ronan.design> [docs] reinstate original docs content to resolve conflicts Signed-off-by: flynnduism <dev@ronan.design>

Signed-off-by: flynnduism <dev@ronan.design>

bridgetkromhout · 2020-11-05T20:58:22Z

This looks good. Question, the "feedback" thing links to "https://github.com/USERNAME/REPOSITORY/issues/new" - if we want to use that, where do we customize it with the correct repo?

Also, I think there may be a formatting issue in the footer, as the CNCF statement is staying over on the left:

Finally, there's something weird here: https://osm-docs.netlify.app/docs/design/readme/ - this is listed in the sidebar as Onboarding VMs (which also has another link):

Other than these minor issues, I think it's pretty great. Do we merge it now and just not link it from the front page until you have all the content as desired?

phillipgibson · 2020-11-05T21:01:05Z

I'm fine with getting it merged to get it live and we can clean up those details you called out.

bridgetkromhout · 2020-11-05T21:08:32Z

@phillipgibson Okay! I think if you approve the changes as well, @flynnduism will be able to merge it.

shashankram · 2020-11-05T21:14:58Z

@flynnduism Once this change is merged, does it affect how new documents are added/updated by developers or is the website generation transparent?

bridgetkromhout · 2020-11-05T22:30:40Z

docs/README.md

+
+* built with the [Hugo](https://gohugo.io/) static site generator
+* custom theme uses [Docsy](https://www.docsy.dev/) as a base, with [Bootstrap](https://getbootstrap.com/) as the underlying css framework and some [OSM custom sass](https://github.com/openservicemesh/osm/pull/1840/files#diff-374e78d353e95d66afe7e6c3e13de4aab370ffb117f32aeac519b15c2cbd057aR1)
+* deployed to [Netlify](https://app.netlify.com/sites/osm-docs/deploys) via merges to master. (@flynnduism can grant additional access to account)


master

main

bridgetkromhout · 2020-11-05T22:31:11Z

docs/README.md

+
+## Deploying the site:
+
+The site auto deploys the master branch via [Netlify](https://app.netlify.com/sites/osm-docs). Once pull requests are merged the changes will appear at docs.openservicemesh.io after a couple of minutes. Check the [logs](https://app.netlify.com/sites/osm-docs/deploys) for details.


master

main

bridgetkromhout · 2020-11-05T22:31:34Z

docs/themes/dosmy/layouts/partials/page-meta-links.html

+{{ $gh_repo := ($.Param "github_repo") }}
+{{ $gh_subdir := ($.Param "github_subdir") }}
+{{ $gh_project_repo := ($.Param "github_project_repo") }}
+{{ $gh_branch := (default "master" ($.Param "github_branch")) }}


master

main

flynnduism requested a review from a team as a code owner October 14, 2020 22:26

flynnduism self-assigned this Oct 14, 2020

flynnduism force-pushed the docs-www branch from 990f3c3 to efbeab5 Compare October 14, 2020 22:53

flynnduism force-pushed the docs-www branch from 02faa72 to 13f5fa3 Compare October 27, 2020 16:42

flynnduism force-pushed the docs-www branch from ff32aaa to d927f74 Compare October 27, 2020 19:30

flynnduism mentioned this pull request Oct 27, 2020

Netlify bot causing PR check failures #1930

Closed

phillipgibson previously approved these changes Nov 2, 2020

View reviewed changes

phillipgibson requested a review from bridgetkromhout November 2, 2020 22:30

bridgetkromhout reviewed Nov 3, 2020

View reviewed changes

flynnduism added 14 commits November 5, 2020 12:01

[docs] add base hugo config

3e6b69b

Signed-off-by: flynnduism <dev@ronan.design>

[docs] build on top of docsy theme

b3db275

Signed-off-by: flynnduism <dev@ronan.design>

[docs] move markdown files into hugo content dir

6727282

[docs] add theme files

d8ca82d

[docs] tweak netlify build

85cda70

[docs] add css cache

41280a7

[docs] use a compatible hugop version

b36ff96

[docs] debugging netlify hugo build

0b120e4

Signed-off-by: flynnduism <dev@ronan.design>

[docs] latest docs for rebase resolution

357ed93

Signed-off-by: flynnduism <dev@ronan.design>

[docs] reinstate original docs content to resolve conflicts

445ba11

Signed-off-by: flynnduism <dev@ronan.design> [docs] reinstate original docs content to resolve conflicts Signed-off-by: flynnduism <dev@ronan.design>

[docs] add README and docs versioning

981ce58

Signed-off-by: flynnduism <dev@ronan.design>

[docs] ensure https

04af8f2

[docs] post rebase cleanup

07208c6

Signed-off-by: flynnduism <dev@ronan.design>

[docs] adjust code block css style

368ef1b

Signed-off-by: flynnduism <dev@ronan.design>

flynnduism dismissed phillipgibson’s stale review via 368ef1b November 5, 2020 20:37

flynnduism force-pushed the docs-www branch from d927f74 to 368ef1b Compare November 5, 2020 20:37

flynnduism requested a review from bridgetkromhout November 5, 2020 20:38

bridgetkromhout approved these changes Nov 5, 2020

View reviewed changes

bridgetkromhout reviewed Nov 5, 2020

View reviewed changes

phillipgibson approved these changes Nov 5, 2020

View reviewed changes

phillipgibson merged commit 574731d into openservicemesh:main Nov 6, 2020

flynnduism mentioned this pull request Nov 6, 2020

[docs] configure docs site deployments #2004

Closed

3 tasks

flynnduism mentioned this pull request May 21, 2021

[docs] organize the docs openservicemesh/osm-docs#84

Closed

5 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[docs] render the documentation as a website #1840

[docs] render the documentation as a website #1840

flynnduism commented Oct 14, 2020

shashankram commented Oct 14, 2020

flynnduism commented Oct 15, 2020

flynnduism commented Oct 19, 2020 •

edited

Loading

flynnduism commented Oct 27, 2020

codecov-io commented Oct 27, 2020 •

edited

Loading

flynnduism commented Oct 27, 2020 •

edited

Loading

bridgetkromhout Nov 3, 2020

flynnduism Nov 5, 2020 •

edited

Loading

bridgetkromhout commented Nov 5, 2020

phillipgibson commented Nov 5, 2020

bridgetkromhout commented Nov 5, 2020

shashankram commented Nov 5, 2020

bridgetkromhout Nov 5, 2020 •

edited

Loading

bridgetkromhout Nov 5, 2020

bridgetkromhout Nov 5, 2020


		![OSM Install Demo](https://github.com/openservicemesh/osm/raw/main/img/osm-install-demo-v0.2.0.gif "OSM Install Demo")

		See the [installation guide](docs/installation_guide.md) for more detailed options.


		## Deploying the site:

		The site auto deploys the master branch via [Netlify](https://app.netlify.com/sites/osm-docs). Once pull requests are merged the changes will appear at docs.openservicemesh.io after a couple of minutes. Check the [logs](https://app.netlify.com/sites/osm-docs/deploys) for details.

[docs] render the documentation as a website #1840

[docs] render the documentation as a website #1840

Conversation

flynnduism commented Oct 14, 2020

shashankram commented Oct 14, 2020

flynnduism commented Oct 15, 2020

flynnduism commented Oct 19, 2020 • edited Loading

flynnduism commented Oct 27, 2020

codecov-io commented Oct 27, 2020 • edited Loading

Codecov Report

flynnduism commented Oct 27, 2020 • edited Loading

bridgetkromhout Nov 3, 2020

Choose a reason for hiding this comment

flynnduism Nov 5, 2020 • edited Loading

Choose a reason for hiding this comment

Recommended follow-up edits:

bridgetkromhout commented Nov 5, 2020

phillipgibson commented Nov 5, 2020

bridgetkromhout commented Nov 5, 2020

shashankram commented Nov 5, 2020

bridgetkromhout Nov 5, 2020 • edited Loading

Choose a reason for hiding this comment

bridgetkromhout Nov 5, 2020

Choose a reason for hiding this comment

bridgetkromhout Nov 5, 2020

Choose a reason for hiding this comment

flynnduism commented Oct 19, 2020 •

edited

Loading

codecov-io commented Oct 27, 2020 •

edited

Loading

flynnduism commented Oct 27, 2020 •

edited

Loading

flynnduism Nov 5, 2020 •

edited

Loading

bridgetkromhout Nov 5, 2020 •

edited

Loading