Fix #2418: Building docs should be a part of the CI.

[ankusharya]

In this commit:

• Add action build-docs
• Modify docs/user/sbt.rst to remove the warning

Explanation about build-docs action

• Build on top of sphinx-action
• Update Sphinx to 4.2.0
• Warning in building docs bubble as GitHub warning
• Action build-docs is tested locally by nektos/act

[WojciechMazur]

Thank you for your contribution. I have two comments that should be addressed before merging this change.

[WojciechMazur]

The current setup would not treat warnings as errors, most of the problems with our docs building in the past were in most cases informed as warnings, but they were ignored, eg. missing entry in the index. We should add "-W" option to enable fatal warnings, --keep-going to not stop after the first warning and optionally -n which would try to check for missing references

Suggested change

	docs-folder: "docs/"
	build-command: 'make html SPHINXOPTS="-W --keep-going -n"'
	docs-folder: "docs/"

[ankusharya]

Hi,
Before raising pull request, I thoroughly checked for all the options to make warning as error.
I have checked on adding -W but it does not work.
To solve it I had already raised issue.

• Add -W support
• Add number of warning as step output

Even with one issue resolved, we can enable warning as error.

I also looked into catching warning as they bubble as Github warning, but i dont see any reference of any such workflow commands
If you find any resources/approach, please share. I will implement it.
Any thoughts?

[WojciechMazur]

@ankusharya I think that maybe problems with log files might be also a problem with running with act. We should check if it behaves the same in GH Actions environments in the same way. I don't have a large experience with this tool, but even then I came to corner cases where build was failing locally with act and worked well in the CI

[tanishiking]

It seems like -W didn't work with sphinx-action (action will fail with /tmp/sphinx-log couldn't find) when we use make to invoke sphinx. In this case the SPHINXOPTS collapses between our SPHINXOPTS and internal SPHINXOPTS.

in env=dict(os.environ, SPHINXOPTS=sphinx_options), the sphinx_options will be ignored.
https://github.com/ammaraskar/sphinx-action/blob/e781e9af3e80bfe0ea539e4ea46858d51e027214/sphinx_action/action.py#L114-L123

To workaround this, we can build sphinx by sphinx-build instead of make.

ebb3ac8

[tanishiking]

FYI @ankusharya @WojciechMazur
I rebased the PR on main branch and made it work with sphinx-build on CI, if there's a warning the CI will fail like this:
https://github.com/scala-native/scala-native/actions/runs/5043307827/jobs/9044935416
(sorry to directly push changes onto your branch)