[REQUIREMENT][Ruby] Source code documentation for every release build that is published.

[jessiejuachon]

Is your feature request related to a problem? Please describe. Source code documentation in https://vmware.github.io/singleton/docs/overview/singleton-sdk/ for every release build that is published.

Describe the solution you'd like

1. Run rdoc -include ./lib/ README.md under root directory. This will generate/update a doc directory in root. The doc directory will contain auto-generated html files from source code.
2. See sample index.html generated in my local machine:
3. Have the doc directory published under the resources folder, and the README.md published under the singleton-sdk folder in the website branch.

Describe alternatives you've considered https://ruby.libhunt.com/rdoc-alternatives

[nannany00]

@jessiejuachon , I think the document should be generated and published when release build is published, not in CI for each successful build, could you help confirm?

[jessiejuachon]

@jessiejuachon , I think the document should be generated and published when release build is published, not in CI for each successful build, could you help confirm?

@nannany00 , yes Step 3 should be when release build is published. However, steps 1 and 2 should be at every CI build, so that the docs reflect what is in code at the time of build.

Also, I see 2 branches for documentation: 'gh-pages' and 'website'. The 'gh-pages' branch seems to be more updated, but the 'website' branch seems to be the one displayed in https://vmware.github.io/singleton/docs/overview/. Could you please shed some light?

[nannany00]

@jessiejuachon, thanks for confirming, then I think we can split this task to two: one for ci, one for document generation for release build publish.

Yes, we have 2 branches for document publish, "website" is to store the original MD documents, after new document added into this branch, we will use Hugo to push updated content to "gh-pages", then it will be shown https://vmware.github.io/singleton/docs/overview/;

you see "gh-pages" is more updated, because I remember for java client document, you just push doc html into gh-pages instead of website branch first.

[jessiejuachon]

@nannany00 , yes, let's keep this one for Step 3 only. And on second thought, I think that it should be okay to not have CI run rdoc at every CI build because the documentation is interspersed in source code and can be generated from it anytime anyway.