Add docs workflows

[niksirbi]

I have added the two docs-building actions that I recently updated in the troubleshooting PR. I have tried to follow the structure you had set @adamltyson, so hopefully, I didn't mess anything up. I am not sure how to test if I have set things up correctly, without actually referring to the actions from other repositories. My current plan is:

• Merge this after your approval
• Go back to the troubleshooting PR, remove the workflows from there and replace them with references to this repo.
• If things do not work, come back to this repo and keep tweaking.

Let me know if you have a better idea of how to go about this. Could I in principle call the actions from this branch by referencing neuroinformatics-unit/actions/publish_sphinx_docs@add-docs-workflows? If yes, then I can go back and forth between the 2 PRs and fix things before merging.

I am also unsure how to best integrate these new actions in the full test_and_deploy.yml workflow. Perhaps it would be best to create a second workflow - build_and_publish_docs.yml - which we can choose to include (or not) in other repos, depending on whether these repos contain docs. I can also add this new workflow (alongside a docs folder) to the cookiecutter. In terms of when we choose to trigger these actions, I think a sensible plan is the following:

• Trigger the check_sphinx_docs action upon pull requests
• Trigger the publish_sphinx_docs action when a tag is pushed. This way the docs will be rebuilt every time we release a new software version (an exception can be made for the troubleshooting website, which should be updated with every push to main)

I have tried to add the appropriate conditionals for these triggers in the central README.md examples. Check them out.

[adamltyson]

Merge this after your approval Go back to the https://github.com/neuroinformatics-unit/troubleshooting/pull/11, remove the workflows from there and replace them with references to this repo. If things do not work, come back to this repo and keep tweaking.

I'm not aware of a clever way to do this, so if that's the best we have, then so be it. This is why we only use the released versions in other repositories, so we can mess around in this repo.

Could I in principle call the actions from this branch by referencing neuroinformatics-unit/actions/publish_sphinx_docs@add-docs-workflows? If yes, then I can go back and forth between the 2 PRs and fix things before merging.

I've not tried this, but it sounds like it could work. We could also think about setting up a seperate repo (i.e. a dummy python project with tests and docs etc) to test these actions.

I am also unsure how to best integrate these new actions in the full test_and_deploy.yml workflow. Perhaps it would be best to create a second workflow - build_and_publish_docs.yml - which we can choose to include (or not) in other repos, depending on whether these repos contain docs. I can also add this new workflow (alongside a docs folder) to the cookiecutter. In terms of when we choose to trigger these actions, I think a sensible plan is the following:

Trigger the check_sphinx_docs action upon pull requests
Trigger the publish_sphinx_docs action when a tag is pushed. This way the docs will be rebuilt every time we release a new software version (an exception can be made for the troubleshooting website, which should be updated with every push to main)

I have tried to add the appropriate conditionals for these triggers in the central README.md examples. Check them out.

Sounds very good to me.

[niksirbi]

Let me know if you have a better idea of how to go about this. Could I in principle call the actions from this branch by referencing neuroinformatics-unit/actions/publish_sphinx_docs@add-docs-workflows? If yes, then I can go back and forth between the 2 PRs and fix things before merging.

Turns out that this works as intended, so I went with this option. Will change to @main once this is merged.

[niksirbi]

Now the new actions seem to work as intended. The tricky part was passing the correct secret GitHub token when pulling the publish action from another repository. Accomplished using inputs passed into environment variables.

Perhaps it would be best to create a second workflow - build_and_publish_docs.yml - which we can choose to include (or not) in other repos,

I ended up with separate workflows for check_docs and publish_docs, see the other PR for the reason.