build & publish documentation to gh-pages from GitHub Actions workflow

[prjemian]

• FIX publish documentation from GitHub Actions workflow #953

[prjemian]

Note that until #950 is fixed (by PR #951) and merged into this branch, the Syntax Checks / CI are expected to fail here.

[prjemian]

Let's disable the syntax-checks.yml workflow now to turn off the nuisance emails as they fail.

[prjemian]

Actually, this PR needs #951 first.

[prjemian]

Once the changes from #951 (which will fix the syntax checks) can be merged here, we can test the final publishing step. (Without those fixes, the newly-prepared docs are missing quite a bit content.) Only then would I consider this PR suitable for review.

@PeterC-DLS , @FreddieAkeroyd : That said, could either of you take a look at this before it is marked ready to review?

[prjemian]

To see how this has been run, consult the Actions logs for the Publish Sphinx Docs to GitHub Pages workflow: https://github.com/nexusformat/definitions/actions/workflows/publish-sphinx.yml

[PeterC-DLS]

Looks okay but checks failing strangely...

[prjemian]

The Jenkins occurring must also be adjusted now since the PDFs have moved from the `pdf/` directory (installed after the docs are built) to the `_static` directory before the docs are built. The CI failures will be resolved by the other PRi submitted last Friday. That involves removing common indentation from embedded rst documentation and use of an XML entity in a documentation block.

…

On Mon, Dec 13, 2021, 7:24 AM Peter Chang ***@***.***> wrote: Looks okay but checks failing strangely... — You are receiving this because you were assigned. Reply to this email directly, view it on GitHub <#955 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AARMUMALLCVFOUOKCRYYEYTUQXXZ7ANCNFSM5JZUZXNA> . Triage notifications on the go with GitHub Mobile for iOS <https://apps.apple.com/app/apple-store/id1477376905?ct=notification-email&mt=8&pt=524675> or Android <https://play.google.com/store/apps/details?id=com.github.android&referrer=utm_campaign%3Dnotification-email%26utm_medium%3Demail%26utm_source%3Dgithub>.

[PeterC-DLS]

That's not what the logs say: https://github.com/nexusformat/definitions/runs/4488225359?check_suite_focus=true

[prjemian]

Right. That error has been appearing lately and looks like a problem with pip. Not something NeXus can resolve.

[prjemian]

related documentation to be adjusted:

(base) prjemian@zap:~/.../NeXus/definitions$ git grep /pdf/
manual/source/design.rst:.. [#] https://manual.nexusformat.org/pdf/NeXusIntern.pdf
manual/source/introduction-napi.rst:see the `NeXus Internals manual <https://manual.nexusformat.org/pdf/NeXusIntern.pdf>`_, copied from the NeXus code repository.
nxdl.xsd:                                                       http://manual.nexusformat.org/pdf/NeXusIntern.pdf

[prjemian]

@PeterC-DLS - Now I recall, the workflow failures involving pip were due to the incorrect instructions in /environment.yml that were fixed in #951 (by using a different YAML file for the GH workflow):

definitions/environment.yml

Lines 8 to 9 in 40bd567

	- pip:
	- -r file:requirements.txt

[prjemian]

Is the /environment.yml file necessary now?

[prjemian]

Now that #951 is merged into this branch, the workflow failures (noted above) are resolved.

[prjemian]

@FreddieAkeroyd , @PeterC-DLS : Please review.

[prjemian]

@FreddieAkeroyd Can you review this PR?

[prjemian]

I will merge this PR 2022-02-07 unless there are objections.

[FreddieAkeroyd]

Sorry @prjemian my GH notifications are all over the place. Should the actions be publishing to https://github.com/nexusformat/definitions/tree/gh-pages or do they publish elsewhere?