Mayavi example

[GenevieveBuckley]

This PR adds a mayavi example to the docs.

Closes #16

[smarie]

Hi @GenevieveBuckley sorry for taking so long to finally have a look at this PR!
Could you please update your branch from latest main, to see if by any chances the recent pushes have fixed the build issues ?

[GenevieveBuckley]

I think the problem is adding mayavi as a dependency for the CI testing with nox.
I tried adding it to the list MKDOCS_GALLERY_EXAMPLES_REQS in noxfile.py, but pip is trying and failing to build the mayavi wheel.

ERROR: Failed building wheel for mayavi
ERROR: Could not build wheels for mayavi, which is required to install pyproject.toml-based projects
Failed to build mayavinox > Session tests-3.11 failed.

[GenevieveBuckley]

Found more details here: enthought/mayavi#1232

[GenevieveBuckley]

1. mayavi only supports python>=3.8, so the python 3.7 CI tests are failing during the installation of the test requirements.
   How do you want to handle this? Keep the python 3.7 CI jobs and somehow skip/exclude the mayavi test? Or run all the tests for all jobs, and drop support for python 3.7?

2. I'm also having some problems with OpenGL on Windows. I'm not sure how to fix that right now.

generating gallery for D:\a\mkdocs-gallery\mkdocs-gallery\docs\generated\gallery... :  92%|#########2| 12/13 [00:11<00:01,  1.44s/it]2023-11-21 02:05:01.874 (  11.803s) [D68EC05383278E3C]vtkWin32OpenGLRenderWin:669    ERR| vtkWin32OpenGLRenderWindow (00000270C6930450): failed to get wglChoosePixelFormatARB
ERR: 2023-11-21 02:05:01.969 (  11.898s) [D68EC05383278E3C]vtkWin32OpenGLRenderWin:747    ERR| vtkWin32OpenGLRenderWindow (00000270C6930450): failed to get valid pixel format.
ERR: 2023-11-21 02:05:01.971 (  11.900s) [D68EC05383278E3C]vtkOpenGLRenderWindow.c:704    ERR| vtkWin32OpenGLRenderWindow (00000270C6930450): GLEW could not be initialized: Missing GL version
nox > Command python -m mkdocs build failed with exit code 3221226525

[smarie]

Thanks @GenevieveBuckley ! I guess that the best way to get this released would be to disable mayavi in the CI for python 3.7 and windows targets.

So in the nox session def tests you could maybe add an "if platform is linux and session.python >=3.8 then use MKDOCS_GALLERY_EXAMPLES_REQS + MKDOCS_GALLERY_EXAMPLES_MAYAVI_REQS" else only use MKDOCS_GALLERY_EXAMPLES_REQS

Since there are no tests related to mayavi, the session should pass ok.

[GenevieveBuckley]

Since there are no tests related to mayavi, the session should pass ok.

This is not quite true. Although the pytest command passes successfully, the nox tests function also includes two python -m mkdocs build commands which causes an error when it tries to create the docs/examples/plot_10_mayavi.py gallery example.

I know how to exclude files from the mkdocs gallery with ignore_pattern, but I do not know how I can do this ONLY for certain python versions. Do you have a suggestion for this?

[GenevieveBuckley]

Indeed ! And this is actually quite reassuring, I now remember that decision : "even if I am not able to port all tests here, let's consider that building our own doc successfully is also a test and can count for coverage"

Yeah, I agree that's a good way to do it.

I've got it working now. I notice there are no MacOS tests, is that intentional?

[Louis-Pujol]

Hi @GenevieveBuckley ! I see that you are experiencing some troubles with vtk and GitHub Actions. If not already done, I suggest you to try this action from pyvista (pyvista is also vtk-based). I had similar error messages and everything works like a charm since I use it.

[smarie]

Thanks @GenevieveBuckley ! Last round of comments, but overall looks fine to me.

No I did not add macOS targets, mostly because on most codebases usually ubuntu is enough to guarantee mac portability. But if for specific scrapers you believe that this makes sense, then let's add them ! (in a separate PR though)

[GenevieveBuckley]

It's working now! The pyvista headless github action seems to have completely fixed the mayavi install problems I had on Windows. So now it's only the python 3.7 sessions that skip mayavi (because mayavi only supports python >=3.8).

[smarie]

Great, thanks a lot @GenevieveBuckley !

[smarie]

It looks great ! https://smarie.github.io/mkdocs-gallery/generated/gallery/plot_10_mayavi/

0.8.0 release shipped. Thanks again for this nice contribution!