Create a GitHub action to publish white labeled ODP Docusaurus content

[mcleo-d]

Acceptance Criteria

• A GitHub Action is available on https://github.com/finos/open-developer-platform to build Docusaurus microsite hosted on odp.finos.org
• Each PR submitted to /docs and website folders has a comment with a link to the site preview
• Demo of GitHub Action to ODP team

Tasks

• Implement GitHub Action that builds Docusaurus, see https://github.com/clay/docusaurus-github-action
• Find a mechanism to build microsite preview and report link as comment for each related PR
• Configure GitHub Action to build ODP microsite
• Demo and discuss further via ODP meeting

[brooklynrob]

Per my discussion with @maoo on 2020.1.31 it's my understanding that this is the issue that would address the need to make it much easier for developers to run builds of documentation sites on their forks, such that they can share their WIP (work in progress) with other collaborators in the form of their fork build of the doc site.

This has come up with Alloy as there are several people who will be working on the documentation site concurrently and it would be useful to share ideas with each other by showing our build on our fork before doing PRs into the base repo.

It sounds like at least part of the work would be to parameterize some of the fields in website/siteConfig.js (e.g., cname, url, baseUrl and .travis.yml, and to also handle different scenarios for if/how a CNAME record is used.

[grizzwolf]

@brooklynrob - I've set up a meeting with @mcleo-d @maoo on Monday to discuss this and a couple of other issues on Microsite / GH UX - and how best to address for users with less technical experience. Plus, we'll discuss some other items that should go into the Documents and branding of microsites (current and future via the microsite blueprint). Thanks

[brooklynrob]

@grizzwolf @mcleo-d @maoo A good example I thought of when discussing this w/ @toshaellison today was the way in which Riko's fork, https://rikoe.github.io/FDC3/docs/use-cases/overview (no longer up) became our de facto staging/testing/integrate environment during the FDC3 doc site says. Grizz's did too.

[brooklynrob]

@grizzwolf @mcleo-d @maoo Versioning might be another way to fulfill this. See https://docusaurus.io/docs/en/tutorial-version. This sentence, especially the last part, is what caught my eye: "Versioned documentation helps to show relevant documentation for the current version of a tool and also hide unreleased documentation from users, reducing confusion." -- I am looking for a way to stage/test/show documentation to a small group of reviewers for comment first before releasing it to everyone.

[brooklynrob]

Another idea for how to implement this (a staging/integration environment in which to stage/evaluate proposed documentation changes) for, say, Alloy.

• (Current) Production: Doc commits made to master branch configured to build and deploy pages into the gh-pages branch, which deploys to alloy.finos.org
• (Suggested) Test/Stages: Commits made/merged to a (say) docs-test branch configured to build and deploy pages into the gh-pages-test branch, which deploys to alloy-test.finos.org. Changes promoted from test to production as ready to go/approved.
• (Optional) Dev: Commits made/merged to a docs-dev branch configured to build and deploy pages into the gh-pages-dev branch, which deploys to alloy-dev.finos.org

I.e., use the same build infrastructure and process, and make use of branches and two new hostnames to create 1 or 2 more instances (test and dev). Additionally, probably make process that pull requests are merged into the lowest (i.e., test if there is no dev; otherwise dev) level and then commits promoted as part of the editorial review process.

[maoo]

Working on a promising spike on https://github.com/maoo/finos-fo/blob/master/PUBLISH_SITE.md

Still need to test the PR comment feature, but the build works like a charm and doesn't need any configuration (as opposed to the Travis CI approach we followed so far).

When all is tested and working, we will adopt this build on https://github.com/finos/open-developer-platform and test the full PR workflow.

[mcleo-d]

I believe we're talking about two different features of microsite development on this thread, so have created...

• Create a build feature that allows FINOS microsite developers to demonstrate their in-development Docusaurus sites from their forks Create a build feature that allows FINOS microsite developers to demonstrate their in-development Docusaurus sites from their forks #60

... to follow the in-development microsite feature raised by @brooklynrob.

The solution being delivered in this issue #19 is a PR feature that allows project maintainers to review the contents of a microsite PR before accepting the build, which is post development.

[mcleo-d]

@maoo - Thanks for all the work done ask part of this story 😺

Please move this item to In Progress on the ODP kanban if the story has been picked and in play.

https://github.com/orgs/finos/projects/8#card-31823971

Please note, I have raised #60 to capture the requirements of @brooklynrob which could be different to the scope of this story.

Thanks buddy 👍

[maoo]

Code is done and running, see https://github.com/finos/open-developer-platform/blob/master/docs/docusaurus-build-action.md

The comment feature is currently failing with a 403 ; I found a similar issue on danger/danger-js#918 , would be worth asking GitHub how we can make it work.

Happy to demo this action during the next ODP meeting!

[maoo]

Just created #74 and #75 with the issues left, so we can close this one.

Docs available on https://finosfoundation.atlassian.net/wiki/spaces/FDX/pages/1411317820/Docusaurus+Build+Action