Running makefile on Windows

[RCF42]

So I'm just going to bring the discussion from my pull request over to here since I think that the issue may be universal. So Windows can't natively run make and makefiles and instead has to use nmake and the file that goes with that. I came across a solution to install a make for windows function using chocolatey here and now I can use the make command natively but I'm still facing the same issue as before that when I run make html it still returns, for every single tutorial:
E:\robert\Documents\GitHub\MPoL\docs\index.rst:33: WARNING: toctree contains reference to nonexisting document 'tutorials/_____'

I think for my next step I'll try making a version of the makefiles that are the windows compatible ones and see if it works then, if so maybe it'll be possible to just include both.

[iancze]

I'm not familiar with nmake (other than what I just looked at in the docs) but this seems like a good approach to try first. Hopefully the nmake file ends up being easy to generate from the current Makefile.

You could also try writing a make.bat script. Sphinx provides a default script when a repository is initialized. I think this would be more of just a "run everything everytime" and lose some of the dependency checking behavior of Make, but it's a potential solution.

In the end, the final versions of the docs will be built on Github Actions using Ubuntu-latest, so the ability to build the docs on Windows is really only important in so far as it helps you in the development cycle. If you can manage the development cycle by building + viewing the notebook version of the *.py file using jupytext directly, that's probably good enough.

[RCF42]

After looking into nmake more I think I'll just stick with manually doing it, though I'm going to set up a Linux VM on my computer and in the future see how my local branch works on that.

[trq5014]

I think the windows makefile/bat file is a good idea. I was able to compile the docs from your forked branch on my mac but ran into the same issues compiling the docs on both of my windows machines. The issue seems to be specifically for the tutorials/.py files so maybe look into this a bit? I plan on seeing if I can find a quick fix today

[trq5014]

I just wanted to note that when I was messing around with this earlier I discovered that it isn't an issue with making the actual .ipynb files. I was able to do this manually (i.e. jupytext --to ipynb --execute tutorials*.py), from the ./docs/ directory. Once doing this, the make file had no issue with compiling the docs for all the tutorials. I will look into what may be causing the makefile to not run this command when executing.

[iancze]

I think this is something specific to the version of make that's default to windows not behaving the same as GNU Make (default to Unix/Linux environments). From a fresh install, make html --dry-run should show a list of dependencies that need to be build before running Sphinx. At least when Robert and I were investigating things, it went straight to running Sphinx without doing the jupytext commands you mentioned, suggesting something about the dependency checking isn't working properly.