nbsphinx
nbsphinx copied to clipboard
spatialaudio
Github action for generating docs using nbsphinx
Via a Jupyter discourse thread on using Github actions to automatically build MyBinder images from pushes to a Github repo, I wondered if there is an example nbsphinx Github action defined anywhere?
Eg I note this https://github.com/ammaraskar/sphinx-action
I have never used Github Actions, and I don't know whether anyone has used it with nbsphinx.
Did you try if the above-mentioned Sphinx action works?
I guess it should work fine if you can specify the nbsphinx requirement (which I guess you can do with a requirements.txt file).
I guess the "fancy in-line warnings" will not work because nbsphinx doesn't track line numbers in .ipynb files.
OK, I quickly tried it, and I found two problems:
- A
Makefileis needed (see https://github.com/ammaraskar/sphinx-action/issues/2) - I don't know how to install
pandoc
No need to use Sphinx-action, you can just run the commands as you normally would. I got a first example working on my branch for the PR.
Pandoc and librsvg can be installed with conda, for osx and Linux. If it wasn't for librsvg, it would even work on windows. With tectonic, you can even compile latex cross platform.
Cool, I'm looking forward to this PR!
As far as I'm concerned, you don't have to support Python 2 in your efforts, I was planning to drop Python 2 support in early 2020 anyway.
If it wasn't for librsvg, it would even work on windows.
Shouldn't it work on Windows?
At least there's a win32 directory: https://gitlab.gnome.org/GNOME/librsvg/tree/master/win32
I guess the problem is that Windows isn't supported on the conda-forge package, right?
With tectonic, you can even compile latex cross platform.
Cool, I didn't know this project!
... but I don't know if we really need to generate the PDF on multiple platforms?
@psychemedia if you just want to rebuild your binder image, when i.e. master is updated you can use this action.
@s-weigand Thanks for that; I'm wary of rebuilding too often on MyBinder - I often make piecemeal pushes / do edits on single files via Github UI, and some of my Binder images force quite lengthy builds!
PS I've also started looking at this action — https://github.com/machine-learning-apps/repo2docker-action — for building images from repos using repo2docker and then pushing the result to Dockerhub.
In the meantime, I've used Github Actions in a different project, see https://github.com/AudioSceneDescriptionFormat/splines/blob/master/.github/workflows/docs.yml.
This uses https://github.com/dante-ev/latex-action for building the PDF. It uses quite a big image, which needs nearly 3 minutes to load. Maybe using tectonic, as @s-weigand suggested above (https://github.com/spatialaudio/nbsphinx/issues/358#issuecomment-566205536), is faster, but I didn't try it (yet).