New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Error when building nbsphinx docs - folder name is invalid #629
Comments
This looks like your system doesn't support symbolic links. This is supposed to be a symbolic link: https://github.com/spatialaudio/nbsphinx/blob/master/doc/gallery/ipython_kernel_config.py I don't know how, but I guess there's some way to get symlinks on Windows?
This command is kinda old school and nowadays it isn't recommended anymore. It will even be removed at some point (see sphinx-doc/sphinx#9595). I should probably stop recommending it. You can use |
Oh, and I just spotted another problem (maybe the main problem): in You seem to be building the stuff in It would be easier if you run Sphinx from the main directory with something like this:
This way, the |
Well, git symbolic links do not work nicely on Windows. My first google hit was https://stackoverflow.com/questions/5917249/git-symlinks-in-windows and it looks like there is a solution somehow but a bit tricky. I will try it out. And thanks for the update on the building command! |
Most of the answers are very old, this one seems reasonably recent: https://stackoverflow.com/a/59761201/. |
Well, it improved:
The first step was deleting the build directories. Then I did as specified in the answer you highlighted. Maybe the system requires a reboot or some other default Windows magic to finally make the links work. |
One of the comments on the SO answer says: "Also you have to re-clone repository to make symlinks work with it" Did you do that? |
Nope, I will do that next. Another source said that switching back and forth branches would do the job and it obviously did not work. Thus, I will follow the suggestion of just cloning everything again. Besides the symlink, the command |
With the fresh clone, now the links resolve as well. There are a few warnings left but I hope that they are "normal".
|
Yes, the one about Sphinx Gallery and Jupytext can be ignored, since we only use the CSS styling from Sphinx Gallery. The other one can be ignored as well, but I'm still working on removing it, see #559. |
I added a bit text to the documentation as we previously discussed at #624. I found the description in https://github.com/spatialaudio/nbsphinx/blob/master/CONTRIBUTING.rst about how to build the documentation.
The last error message translates to "folder name is invalid. When I ran this code for the first time, the folder
build
without the prefix underscore was created and the subdirectorydoctrees
was filled. Now it is frequently updated with every execution. The neighbouring directoryhtml
stayed empty. The folder_build
(with prefix) that was built when I ranpython -m sphinx -W --keep-going --color -d _doctrees/ doc/ _build/linkcheck/ -b linkcheck
(I took it from https://github.com/spatialaudio/nbsphinx/blob/master/.github/workflows/linkcheck.yml) has ben untouched since the last execution.Could you shortly explain how
python setup.py build_sphinx
works and where it takes its default configuration from? It feels like one of the dependencies used here changed over time and now there is an issue. This assumption requires further examination of course.The text was updated successfully, but these errors were encountered: