Jupyter-book: Path issues with sub-folders under windows

[DavidPowell]

I am using the latest 0.7.0b2 on Windows 10, with Anaconda Python 3.7.

I am able to create and compile the template project as per the project documentation. However, building fails when I move a file to a subfolder (which I need to do for a much larger document). To reproduce the issue:

• Move contend.md to folder\content.md
• Modify _toc.yml so that the relevant line read - file: folder/content
• Clean, then rebuild the book

The build is successful, but several files are no longer included, with the output given below. It appears to be an issue with relative paths using \\.

I believe that this is due to how jupyter-book converts windows paths before handing on to Sphinx, as I have had no problems running Sphinx with a heavily nested project on this machine.

<project root path>\folder\content.md:7: WARNING: toctree contains reference to nonexisting document 'folder/..\\markdown'                                                                               
<project root path>\folder\content.md:7: WARNING: toctree contains reference to nonexisting document 'folder/..\\notebooks'                                                                              
<project root path>\intro.md:9: WARNING: toctree contains reference to nonexisting document 'folder\\content'                                                                                            
looking for now-outdated files... none found                                                                                   
pickling environment... done                                                                                                   
checking consistency... <project root path>\folder\content.md: WARNING: document isn't included in any toctree                                                                                           
<project root path>\markdown.md: WARNING: document isn't included in any toctree                                                                                                                         
<project root path>\notebooks.ipynb: WARNING: document isn't included in any toctree                                                                                                                     

[zugkraft]

Same issue here (0.7.0b2 on Windows 10, Python 3.7) on two different machines

[choldgraf]

Yep @amueller ran into this as well. I am going to try building on Windows to figure out where the breaking points are. It may take me a bit of time because I have no idea how to install Anaconda on windows 😅.

If anybody has expertise in developing Python for Windows, PRs would be fantastic. I'd also be +1 on adding a windows build to the CI/CD. For now, I'm going to add a warning to the documentation that Windows support is experimental.

[amueller]

I can try but don't want to promise anything ;)

[phaustin]

note that the quantecon example has a more interesting problem with timetuple, planning to look at this, but probably end of week: https://github.com/executablebooks/quantecon-example/pull/10#issuecomment-626988469

[choldgraf]

@phaustin I'm trying to collect all of the known windows issues here: #575 - should we add this as well?

[phaustin]

for sure -- definitely points to the need for ci with windows.

[choldgraf]

yeah - though it will be hard to guarantee windows support until we have reliable developer time that is familiar with Windows. I don't have the bandwidth to figure out windows-specific issues each time they come up, since I have no experience coding in windows :-/

[phaustin]

definitely get the impression that we're all unix immigrants here. I'm writing a windows developer guide (4 of our group of 6 on our project are windows users which is why I spent my weekend on windows).
for anyone in my situation, my two top tips for conda on windows:

1) install windows terminal from the microsoft store
2) use a powershell profile (not the anaconda shortcut) to start a conda environment with readline editing and environmental variables:

https://github.com/eoas-ubc/eoas_tlef/blob/master/docs/support_files/Microsoft.PowerShell_profile.ps1

[amueller]

@phaustin is that useful even if you don't know powershell? The anaconda shell seem pretty terrible. it doesn't support terminal colors so the output of sphinx is real mangled. Would love to see an "anaconda on windows" guide.

[phaustin]

definitely -- powershell is much closer to bash, so ls, cd ~ etc just work:
https://eoas-ubc.github.io/eoas_tlef/pyman/notebooks/course_bootstrap/python.html#powershell-and-bash-common-commands

and any iterm2 colormap is also available for windows terminal:
https://github.com/eoas-ubc/eoas_tlef/blob/master/docs/support_files/windows_terminal_settings.json

powershell also has an openssh client so ~/.ssh/config, and scp etc. work just like bash

[DavidPowell]

Thanks all for quickly looking at this. I have just installed jupyter-book under Windows Subsystem for Linux, and the issue does not occur there. So at least for now I have a workaround.

I will be happy to test any fixes that get pushed to master or another branch.

@phaustin regarding shells for windows, I use conemu (I haven't tested the new windows terminal so I can't compare). It and many other windows packages are easily installed from the command line using chocolatey. It can be used with powershell, standard windows shell, and it's easy to create profiles for each of your conda environments if you have multiple of them.

[phaustin]

I'd add that wsl for individual shell commands is also a nice addition -- nice to be able to do:

wsl rm -rf _build/*

from a powershell prompt.