Use make in build sphinx docs

[lochhh]

Description

What is this PR

• Bug fix
• Addition of a new feature
• Other

Why is this PR needed?
This PR adds the optional use-make input to the build_sphinx_docs action to allow docs to be built using the make utility, such that we can use, e.g.:

• make html instead of sphinx-build source build
• make clean html instead of rm -rf build && sphinx-build source build
• make linkcheck instead of sphinx-build source build -b linkcheck

This will also allow custom build targets in the make file, e.g., to automate the API index page generation.

Since make places the built html pages in docs/build/html/, whereas the default sphinx-build places these in docs/build (as pointed out by @niksirbi), the optional use-make input is also added to the deploy_sphinx_docs action to help identify the location of the built documentation for deployment.

To ensure all current repositories using these actions remain unaffected, use-make is set to false by default, i.e. they will continue to use sphinx-build and project maintainers can opt-in as needed.

How has this PR been tested?

This has been tested

• locally in the aforementioned movement PR.
• remotely in a forked movement repository; the auto-generated API pages can be found here

Does this PR require an update to the documentation?

Updated description in all README.mds

Checklist:

• The code has been tested locally
• Tests have been added to cover all new functionality
• The documentation has been updated to reflect any changes
• The code has been formatted with pre-commit

[adamltyson]

Just for my own curiosity:
a) Why do we need/want this
b) Would this have any affect upon local workflows (we have lots of website built using this action now)

[niksirbi]

My understanding is that this has two benefits:

• neater syntax
• the ability to add custom make commands on a per-project basis. In the example linked above, @lochhh added a custom build step in movement that auto-generates the entire API index page.

But I agree that it's important to make sure that this doesn't break projects with the "default" Makefile. Afaik it shouldn't, but maybe we can test that via one such project (e.g. HowTo, NeuroBlueprint), after merging this to main and before we make a new actions release?

[lochhh]

This will work with the default Makefile (created by sphinx-quickstart) - which I believe our projects use?

[niksirbi]

This will work with the default Makefile (created by sphinx-quickstart) - which I believe our projects use?

Yeah, that should be the case. I created the original Makefile with quickstart (including the one in the cookiecutter), and I think all other projects just copied that.

[niksirbi]

Btw I just noticed that if you use sphinx-build the index.html is located in build/index.html, whereas when using make html it's in docs/html/index.html. Will that affect the rendering of the webpage by gh-pages? Maybe the action we use during deployment is robust to that?

[lochhh]

Btw I just noticed that if you use sphinx-build the index.html is located in build/index.html, whereas when using make html it's in docs/html/index.html. Will that affect the rendering of the webpage by gh-pages? Maybe the action we use during deployment is robust to that?

You're right, it will be in docs/build/html/index.html and we will need to change publish_dir to docs/build/html 🤔

[adamltyson]

Before merging can we come up with a plan to make sure every website is going to work fine following these changes. I assume it will all be ok, but just in case, the ones that I know of that use this action are:

• https://neuroinformatics.dev
• https://movement.neuroinformatics.dev
• https://neuroblueprint.neuroinformatics.dev
• https://datashuttle.neuroinformatics.dev
• https://software-skills.neuroinformatics.dev
• https://howto.neuroinformatics.dev
• http://brainglobe.info
• https://ratinabox-lab.github.io/RatInABox

[niksirbi]

And there are others as well:

• https://sainsburywellcomecentre.github.io/WAZP/
• https://brainglobe.info/brainglobe-template-builder/

[niksirbi]

A potential plan:

• Make these changes "optional" via an argument that's false by default, something like the following in both build and publish actions:

  use-make:
    description: 'Build sphinx docs with `make'
    required: false
    type: boolean
    default: false

• Merge and release actions
• Enable this boolean in the workflows for movement and maybe some other low-stakes websites, like HowTo
• After a while, once we're sure it works, for everyone, remove that optional boolean?
• Alternatively we can leave the boolean in and leave the choice up to each website's maintainer

[lochhh]

A potential plan:

• Make these changes "optional" via an argument that's false by default, something like the following in both build and publish actions:

  use-make:
    description: 'Build sphinx docs with `make'
    required: false
    type: boolean
    default: false

• Merge and release actions
• Enable this boolean in the workflows for movement and maybe some other low-stakes websites, like HowTo
• After a while, once we're sure it works, for everyone, remove that optional boolean?
• Alternatively we can leave the boolean in and leave the choice up to each website's maintainer

I've made the changes as suggested and forked the movement repo to test the docs build and deploy.

[niksirbi]

I've made the changes as suggested and forked the movement repo to test the docs build and deploy.

Seems to be working fine, based on the rendered website from the fork.
Time to merge and make a new actions release?

[niksirbi]

Looks good to me now, and I like how you've documented this in the READMEs @lochhh