docs: user documentation on github pages #195

yitsushi · 2021-11-02T17:16:59Z

What this PR does / why we need it:

Documentation site is powered by Docusaurus.
gRPC documentation is generated with protoc-gen-doc.
Getting started documentation is the as the quick-start guide, but
with separate files, so it's easye to navigate and digest the content.
It really needs a refactoring and we have to write a real user Getting
Started docoument.
Enabled blog for now, we can turn it off if we don't want to use it.
Created an example blog post about the v0.1.0-alpha.1 release.
GitHub action to check if the documentation build process is not broken.
GitHub action to deploy documentation from main on push.

Tools:

Docusaurus: https://docusaurus.io/
protoc-gen-doc: https://github.com/pseudomuto/protoc-gen-doc

Which issue(s) this PR fixes:
Fixes #85
Fixes #194

Special notes for your reviewer:

Notice: This is more like an initial documentation site.

Changed the workflow to run on this branch on push and it was able to deploy the documentation site: 61ef4be

Checklist:

squashed commits into logical changes
includes documentation

github-actions · 2021-11-02T17:17:20Z

This PR is so big! Please, split it 😊

codecov-commenter · 2021-11-02T17:20:42Z

Codecov Report

Merging #195 (3173bde) into main (fe9bb9f) will not change coverage.
The diff coverage is n/a.

❗ Current head 3173bde differs from pull request most recent head ed461d5. Consider uploading reports for the commit ed461d5 to get more accurate results

@@           Coverage Diff           @@
##             main     #195   +/-   ##
=======================================
  Coverage   55.81%   55.81%           
=======================================
  Files          44       44           
  Lines        2012     2012           
=======================================
  Hits         1123     1123           
  Misses        781      781           
  Partials      108      108

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 f8622b6...ed461d5. Read the comment docs.

yitsushi · 2021-11-02T18:00:02Z

If you find any linguistic errors, if you have time for it, just commit to this branch. (around 97% of this is just copy-paste)

github-actions · 2021-11-02T19:06:23Z

This PR is so big! Please, split it 😊

userdocs/src/components/HomepageFeatures.js

github-actions · 2021-11-03T08:52:23Z

This PR is so big! Please, split it 😊

github-actions · 2021-11-03T09:02:51Z

This PR is so big! Please, split it 😊

userdocs/docs/getting-started/basics/containerd.md

richardcase · 2021-11-03T09:54:14Z

userdocs/.gitignore

@@ -0,0 +1,20 @@
+# Dependencies


No entirely sure about using the top level userdocs/ directory. Personally, I think it should live under docs/ somewhere......but thats just a preference ;)

I tried to check how others are using docusaurus and I found the Profiles repo as a good candidate to see how they are using it and they have a userdocs in the root. Other (non-weaveworks) public repos are using a website top level directory.

Other than that, I like the separation of docs/ and the documentation website. This is not a document, it's an entire website and happens to use markdown, mostly, but can use japascript (node) and generate content. That would a bit weird to me if I open the docs directory and a see a lot of js files and markdown files with extra language elements in there (--- header, ::: blocks)

Yeah i take the point about separation.

This is not a document, it's an entire website

Then perhaps website or site is more appropriate then?

richardcase · 2021-11-03T09:56:40Z

userdocs/blog/2021-11-02-v0.1.0-alpha.1.md

+tags: [release, announcement]
+---
+
+# v0.1.0-alpha.1


I like that we can have a blog with this 👍

userdocs/docs/getting-started/basics/configuring-network.md

github-actions · 2021-11-03T12:57:10Z

This PR is so big! Please, split it 😊

github-actions · 2021-11-03T13:03:23Z

This PR is so big! Please, split it 😊

github-actions · 2021-11-03T13:13:51Z

This PR is so big! Please, split it 😊

userdocs/src/components/HomepageFeatures.js

userdocs/docs/intro.md

userdocs/docs/grpc/types/proto.md

Callisto13 · 2021-11-03T14:09:29Z

userdocs/docs/grpc/services/microvm/v1alpha1/proto.md

+
+## Scalar Value Types
+
+| .proto Type | Notes | C++ | Java | Python | Go | C# | PHP | Ruby |


this table does not render all too nicely, the 2nd from left column is very squished so you get 1 word per line

Auto-generated with protobuf

userdocs/docusaurus.config.js

Callisto13 · 2021-11-03T14:12:21Z

userdocs/docs/getting-started/basics/interacting-with-the-service.md

+sidebar_position: 5
+---
+
+# Interacting with the service


we could add extra section here about simply building a client using the grpc methods

That sounds more like a "write documentation" than "Initial creation of documentation site"

github-actions · 2021-11-03T14:20:43Z

This PR is so big! Please, split it 😊

github-actions · 2021-11-03T14:20:48Z

This PR is so big! Please, split it 😊

github-actions · 2021-11-03T14:22:23Z

This PR is so big! Please, split it 😊

github-actions · 2021-11-03T14:24:08Z

This PR is so big! Please, split it 😊

Callisto13 · 2021-11-03T14:35:05Z

chill out github-action bot!

github-actions · 2021-11-03T15:06:30Z

This PR is so big! Please, split it 😊

Notice: This is more like an initial documentation site * Documentation site is powered by Docusaurus. * gRPC documentation is generated with `protoc-gen-doc`. * Getting started documentation is the as the quick-start guide, but with separate files, so it's easye to navigate and digest the content. It really needs a refactoring and we have to write a real user Getting Started docoument. * Enabled `blog` for now, we can turn it off if we don't want to use it. Created an example blog post about the v0.1.0-alpha.1 release. * CNAME: docs.flintlock.dev Docusaurus: https://docusaurus.io/ protoc-gen-doc: https://github.com/pseudomuto/protoc-gen-doc Fixes #85

* Apply suggestions from code review * Update proto + readme based on feedback * Remove ADR from the footer * Minor doc changes Co-authored-by: Claudia <[email protected]> Co-authored-by: Richard Case <[email protected]>

Callisto13

happy with this as a starting point

yitsushi added kind/documentation Documentation only kind/feature New feature or request labels Nov 2, 2021

github-actions bot added the size/xl label Nov 2, 2021

yitsushi removed size/xl kind/feature New feature or request labels Nov 2, 2021

github-actions bot added the size/xl label Nov 2, 2021

jmickey reviewed Nov 3, 2021

View reviewed changes

userdocs/src/components/HomepageFeatures.js Outdated Show resolved Hide resolved

yitsushi force-pushed the 85-docs-site branch from 8af36d9 to 3da9eb3 Compare November 3, 2021 08:51

yitsushi force-pushed the 85-docs-site branch from 3da9eb3 to 46e26e0 Compare November 3, 2021 09:02

richardcase reviewed Nov 3, 2021

View reviewed changes

yitsushi force-pushed the 85-docs-site branch from 438dc8c to f8c3e4f Compare November 3, 2021 13:13

Callisto13 reviewed Nov 3, 2021

View reviewed changes

yitsushi and others added 2 commits November 4, 2021 16:25

GitHub action to build (check) and deploy documentation

ed461d5

* Apply suggestions from code review * Update proto + readme based on feedback * Remove ADR from the footer * Minor doc changes Co-authored-by: Claudia <[email protected]> Co-authored-by: Richard Case <[email protected]>

yitsushi force-pushed the 85-docs-site branch from 3173bde to ed461d5 Compare November 4, 2021 15:27

Callisto13 approved these changes Nov 4, 2021

View reviewed changes

yitsushi merged commit 1984d32 into main Nov 4, 2021

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: user documentation on github pages #195

docs: user documentation on github pages #195

yitsushi commented Nov 2, 2021 •

edited

Loading

github-actions bot commented Nov 2, 2021

codecov-commenter commented Nov 2, 2021 •

edited

Loading

yitsushi commented Nov 2, 2021 •

edited

Loading

github-actions bot commented Nov 2, 2021

github-actions bot commented Nov 3, 2021

github-actions bot commented Nov 3, 2021

richardcase Nov 3, 2021

yitsushi Nov 3, 2021

richardcase Nov 3, 2021

richardcase Nov 3, 2021

github-actions bot commented Nov 3, 2021

github-actions bot commented Nov 3, 2021

github-actions bot commented Nov 3, 2021

Callisto13 Nov 3, 2021

yitsushi Nov 3, 2021

Callisto13 Nov 3, 2021

Callisto13 Nov 3, 2021

yitsushi Nov 3, 2021

Callisto13 Nov 3, 2021

github-actions bot commented Nov 3, 2021

github-actions bot commented Nov 3, 2021

github-actions bot commented Nov 3, 2021

github-actions bot commented Nov 3, 2021

Callisto13 commented Nov 3, 2021

github-actions bot commented Nov 3, 2021

Callisto13 left a comment


		## Scalar Value Types

		\| .proto Type \| Notes \| C++ \| Java \| Python \| Go \| C# \| PHP \| Ruby \|

docs: user documentation on github pages #195

docs: user documentation on github pages #195

Conversation

yitsushi commented Nov 2, 2021 • edited Loading

github-actions bot commented Nov 2, 2021

codecov-commenter commented Nov 2, 2021 • edited Loading

Codecov Report

yitsushi commented Nov 2, 2021 • edited Loading

github-actions bot commented Nov 2, 2021

github-actions bot commented Nov 3, 2021

github-actions bot commented Nov 3, 2021

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 Nov 3, 2021

github-actions bot commented Nov 3, 2021

github-actions bot commented Nov 3, 2021

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 Nov 3, 2021

github-actions bot commented Nov 3, 2021

github-actions bot commented Nov 3, 2021

github-actions bot commented Nov 3, 2021

Callisto13 commented Nov 3, 2021

github-actions bot commented Nov 3, 2021

Callisto13 left a comment

Choose a reason for hiding this comment

yitsushi commented Nov 2, 2021 •

edited

Loading

codecov-commenter commented Nov 2, 2021 •

edited

Loading

yitsushi commented Nov 2, 2021 •

edited

Loading