Skip to content

Generated documentation and website#2

Merged
TristanFloch merged 4 commits intomainfrom
documentation
Jul 19, 2023
Merged

Generated documentation and website#2
TristanFloch merged 4 commits intomainfrom
documentation

Conversation

@TristanFloch
Copy link
Copy Markdown

@TristanFloch TristanFloch commented Jul 13, 2023

The CI executes the following steps to generate the website:

  • Install protoc-gen-doc from our GitHub fork and build it. Once our PR merges (Include file reference to types pseudomuto/protoc-gen-doc#522) it would be preferable to switch back to the default installation (using go install).
  • Run protoc-gen-doc to generate a multi-paged api-reference under docs/api-reference, using the .github/templates/api-reference-md.tmpl template file.
  • Upload an artifact composed of generated api-reference files in case someone wants them.
  • Publish the website by pushing to the gh-pages branch using MkDocs Material.

The website can be previewed here: https://aristanetworks.github.io/eossdkrpc.
Local build and preview instructions have been added to the README (that will be public).

The EosSdkRpc HOWTO guide will be added to the documentation on the next PR: #3.

Note: The CI currently publishes the documentation branch instead of main so everyone can have an overview of the generated website. I will change the publishing to master once this PR is approved.

Other note: At the moment, one single workflow file both builds the api reference and deploys the website. It would be preferable to build the api reference on each push, and deploy the website from the main branch only.
A recent GitHub features allows this workflow split in a clean way, but it will only work when workflow files are on the default branch (see documentation note).
My intent is to split workflows after this PR merges.

@TristanFloch TristanFloch self-assigned this Jul 13, 2023
@TristanFloch TristanFloch marked this pull request as draft July 13, 2023 14:22
@TristanFloch TristanFloch force-pushed the documentation branch 4 times, most recently from bb0fc8c to fc96e88 Compare July 17, 2023 13:35
@TristanFloch TristanFloch force-pushed the documentation branch 6 times, most recently from 240e3e6 to 131ad87 Compare July 18, 2023 10:22
Comment thread docs/guides/index.md
@TristanFloch TristanFloch marked this pull request as ready for review July 18, 2023 13:51
@TristanFloch TristanFloch requested a review from bradishp July 18, 2023 13:52
@TristanFloch TristanFloch force-pushed the documentation branch 2 times, most recently from bc64b8e to f0737c8 Compare July 18, 2023 14:01
Copy link
Copy Markdown
Collaborator

@bradishp bradishp left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

While this is not my area of expertise it all looks good to me.

I left some minor NITs and suggestions around the documentation. Once you have addressed those I am happy for this to merge in.

Comment thread docs/api-reference/index.md Outdated
Comment thread README.md Outdated
Comment thread README.md Outdated
@TristanFloch TristanFloch force-pushed the documentation branch 5 times, most recently from c980e96 to f741cc5 Compare July 18, 2023 16:17
@TristanFloch TristanFloch requested a review from bradishp July 18, 2023 17:37
@TristanFloch TristanFloch merged commit a2d58f7 into main Jul 19, 2023
@TristanFloch TristanFloch deleted the documentation branch July 19, 2023 16:55
@TristanFloch TristanFloch removed their assignment Aug 12, 2023
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants