Rules for running docs build

[jb-adams]

Adding some form of user-provided rules could allow the docs build process to be selectively run based on the Github branch. I can think of a few rules:

• do not build docs if the CI job was triggered by a PR
• do not build docs for refactor/*, feature/* type branches
• build docs for master, develop, release/* branches

This will prevent the job from being triggered for every branch/commit, and prevent the unnecessary proliferation of docs in the gh-pages branch.

This could be handled outside the app, but would require custom shell scripts for each CI provider. It might just be easier to implement within the app itself.

[tschaffter]

See https://github.com/ga4gh/gh-openapi-docs/issues/47#issuecomment-706606302

The above workflow supports multiple triggers like push to branches, PR, GitHub releases, etc. A case can be enable by setting the variable PUSH = true. See https://github.com/Sage-Bionetworks/nlp-sandbox-schemas/blob/develop/.github/workflows/ci.yml#L49-L88.

[tschaffter]

I can implement this approach in this repo if you like it. We could then highlight this workflow in the README.

[jb-adams]

Looks good, is there any chance we could put this behaviour into the application itself instead of in the CI workflow? For example, I have a branch here: https://github.com/jb-adams/gh-openapi-docs/tree/feature/64-build-rules that is starting to do this. The .spec-docs.json config has been expanded with a new enabledBranchPatterns property:

{
    "apiSpecPath": "openapi/openapi.yaml",
    "docsRoot": "docs",
    "defaultBranch": "master",
    "branchPathBase": "preview",
    "enabledBranchPatterns": [
        "^master$",
        "^develop$",
        "release/.+"
    ]
}

so if the current branch matches any of the regex patterns, it will run and build docs. I've also added an environment variable to indicate if this is a PR build, which if false it won't run. We could update this to make some more sophisticated decision making about whether to run and/or push.

My motivation for putting this functionality into the app itself is to keep the .travis.yml files for GA4GH specs small without having to re-write logic for the different specs.