Check sphinx docs action only works with specific sphinx versions

[niksirbi]

As we discovered in this PR, the action we rely on for checking that Sphinx documentation builds succesfully breaks with some versions of Sphinx. This problem seems to have appeared after the Sphinx 6.0.0 release (Dec 29 2022). As a temporary solution, Sphinx needs to be constrained to v5, by adding the following line to the docs/requirements.txt of repositories that rely on this action:

sphinx>=5.0,<6.0

The underlying issue probably come from upstream - ammaraskar/sphinx-action - because a very old version of Sphinx is used in the docker image see this PR.

[niksirbi]

In general, the above sphinx-action hasn't been updated recently and has accumulated a number of issues. Relying on it is risky, so I think we have to find some alternative way of checking whether the docs still build

[niksirbi]

@samcunliffe suggested replacing the check_docs action with the solution below:

For the future, we will still need an action that checks the docs build upon PRs (any ideas @samcunliffe ?)

Agree that we want this. You could make the workflow happen on all pushes and pull requests, then put an if guard just before the Deploy step.

  - name: Deploy
    if: github.event_name == 'push' && github.ref_name == 'main'
    env: 
      GITHUB_TOKEN: ${{ inputs.secret_input }}
    uses: peaceiris/actions-gh-pages@v3
    with:
      github_token: ${{ env.GITHUB_TOKEN }}
      publish_dir: ./docs/build

I have a similarish two-job workflow to build and then publish docs for another project. My deploy/upload/publish (whatever you want to call it) happens as a separate job, rather than a step in a single job but an if-guarded step should be equivalent.