pandas-dev
DOC: Generating docs doesn't work if path has whitespaces
Related to #20862
If there are spaces in the path where pandas is installed (e.g. /home/my user/my code/pandas), when building the documentation (i.e. ./doc/make.py html) seems to generate a long list of usage errors like those:
UsageError: %bookmark: too many arguments
UsageError: %bookmark -d: Can't delete bookmark 'ipy_savedir'
@jopenmolles and I have investigated this issue and are able to reproduce this error. We have noticed that the parameters are passed correctly during execution (i.e. the spaces are escaped when executing the command).
Running sphinx-build directly from the command line gives the same error as using make.py, which strongly suggests that the issue is due to sphinx-build rather than because of an error in pandas.
The question now is whether to create a workaround for this, or to leave it until sphinx-build fixes this issue.
Can you copy the whole call the sphinx-build that is failing? I didn't have the impression that sphinx-build was the problem when opened the issue.
@datapythonista I am running the following command,:
sphinx-build -b html -j 4 -d /home/max/contain\ space/pandas/doc/build/doctrees /home/max/contains\ space/pandas/doc/source /home/max/contains\ space/pandas/doc/build/html
Note that the contains space folder contains a space.
Thanks, I was getting confused with another issue where docs were failing in windows.
If you have time, would be great to try to reproduce the error in a minimal project. I think the bug can be in:
- Sphinx
- A sphinx extension
- pandas specific
And the first step to fix the problem would be to know who should fix it.
@datapythonista A minimal example can be constructed by using the config file provided by running conf.py, adding the IPython.sphinxext.ipython_directive extension. A pastebin can be found here. Let the index.rst have the following contents:
.. ipython:: python
answer = 42
Using this setup in a folder called contains space, run the following command:
sphinx-build /home/max/contains\ space/ /home/max/contains\ space/build
This creates the following log, in which the error is outputted:
Running Sphinx v1.8.4
making output directory...
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 1 source files that are out of date
updating environment: 1 added, 0 changed, 0 removed
UsageError: %bookmark: too many arguments
UsageError: %bookmark -d: Can't delete bookmark 'ipy_savedir'
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] index
generating indices... genindex
writing additional pages... search
copying static files... done
copying extra files... done
dumping search index in English (code: en) ... done
dumping object inventory... done
build succeeded.
When inspecting the resulting html files, it still seems like the interactive python is rendered correctly, however I do not know whether the same is the case for the complete pandas documentation.
I would therefore conclude that this is due to the Sphinx IPython extension, since running the same command on the folder with unedited sphinx-quickstart contents does not throw the same error.
this is useful @MaxVanDeursen, can you create an issue in the ipython project then: https://github.com/ipython/ipython/issues and link it here.
Explicit xref: https://github.com/ipython/ipython/issues/11606
Do you think that there's anything to be done until the issue is of IPython is ultimately fixed?
for what I understand, when the ipython directive is fixed, this will be resolved, nothing to do in our side
I can't reproduce this on latest main on linux. Likely has been fixed?
first time contributor , i wanna work on this issue , just need a little guidance if possible
Per https://github.com/pandas-dev/pandas/issues/22836#issuecomment-1697923245 this has likely been fixed so closing
