Auto build docs via Actions

[tautomer]

Currently two ways to trigger this action

• a push to main
• manual trigger from the Actions tab

The new target in Makefile is renamed to "html_all", which does make apidoc && make html. Original make html should work as before. "all" alone will be ambiguous. It may refer to all file types.

I think it makes sense to directly add this to main or an orphan branch which only hosts the actions.

• Manual trigger only works the default branch. If we add this to another branch, there is no way to manually trigger this action unless you switch default to that branch. And there is no push to main at this moment, so we won't have any docs built for a long time.
• All actions in different branches will (probably) be triggered at the same time, so we either have only one copy of actions on main, or one copy on a separated branch which is only used to host all kinds of actions. Let me if you want to opt for the second way. We can create an orphan branch to do this to minimize "pollutions" to the main codebase.

To make this work, you need create an orphan branch first. Let's say it's called gh-pages like what's in the action. As you need something added to commit, you can create a dummy index.html.

git switch --orphan gh-pages
touch index.html
git add .
git commit -m 'initial commit'
git push --set-upstream origin gh-pages

Then on GitHub, point pages to this branch

Once this PR is merged to main, https://lanl.github.io/hippynn/ should show our docs. The action will take about 3 minutes to finish.

Future CI should be almost the same workflow, but we will want to check the main branch, development branch, and PRs.

[lubbersnick]

Manual trigger only works the default branch. If we add this to another branch, there is no way to manually trigger this action unless you switch default to that branch. And there is no push to main at this moment, so we won't have any docs built for a long time.

slightly confused here, does that mean the file will only work on the main branch, or the action trigger will only work on the main branch?

All actions in different branches will (probably) be triggered at the same time, so we either have only one copy of actions on main, or one copy on a separated branch which is only used to host all kinds of actions. Let me if you want to opt for the second way. We can create an orphan branch to do this to minimize "pollutions" to the main codebase.

I would like to avoid a scenario where we need to keep the file only on a specific branch, that sounds very confusing to manage...

If manual trigger only works for the default branch, is that much of a problem? We can just make sure to trigger it when we PR back from development to main. Would that alleviate the problem with triggering other branches?

Trying to read docs on actions to understand...

[tautomer]

slightly confused here, does that mean the file will only work on the main branch, or the action trigger will only work on the main branch?

Sorry for the confusion. Turns out I was confused as well. I have checked the docs, stack overflow, and created a repo myself for tests. There is still something contradictory.

1. A workflow seems to only work on the branch where it lives in. For example,

   • Workflow on branch A watching pushes to branch B will NOT work, unless branch B has the same workflow (watching itself).

     • This means that if we have multiple workflows on different branches all watching main, there will NOT be multiple actions. Only the one on main will run if it exists.
     • If there is a workflow on main working multiple branches, like

     on:
       push:
         branches:
           - main
           - dev
           - test

     and this file only exists on main, pushes to dev and test will not trigger actions. This behavior is rather weird, especially if you consider that you are allow to specify multiple branches, including wildcards and regex's or even any push to any branch.

     • My hypothesis to this is that if we assume that all branches are ultimately checked out from the main branches, this workflow folder will inherit, such that all branches in the repo will have the same rules for action triggers. For example,

     on:
       push:
         branches:
           - main
           - 'releases/**' 

     with this, all releases branches will automatically have actions and all other non-default branches won't, unless you explicitly modify the workflow file in that branch. This should minimize conflicts.

     I will double-check this, but this behavior agrees with my tests and many online answers. The syntax and docs are misleading.

2. As for manual triggers, the button

   will only show up if workflow_dispatch exists in the workflow of the default branch. However, adding this line to other non-default branches' workflows will enable you to manually trigger the action on these non-default branches. For example,

   • workflow_dispatch on main only: button shows up + manually run on main,
   • workflow_dispatch on main and dev: button shows up + manually run on main or dev,
   • workflow_dispatch on dev only: no button.

   I guess this feature can be useful in cases for example, we want to check the development docs on github, but we don't want it to auto run, as it will likely be triggered more often than main (then github io will almost always be the development version docs). After building the docs, we can manually trigger main's action to bring the main docs back.

Anyway, to build the documentation for latest main branch, we must have this workflow on main. And because we can't deal with multiple versions of docs, this action can only exist on main.

[lubbersnick]

Ok, so in summary, we can accept this PR to development, and when it gets pulled back into main, everything will work?

Keeping multiple docs around based on releases is something I am willing to look at later. I don't think we're 'supposed' to use branches for releases, but rather tags.

[tautomer]

PR to development

Yep, changed base branch to development.

Keeping multiple docs around based on releases is something I am willing to look at later

We can add "on tags" later. To host multiple versions, we definitely need change something.