DOC: Generating docs doesn't work if path has whitespaces

[datapythonista]

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'

[michaela12]

Hi, I'd like to take this issue if it's still open!

[datapythonista]

Sure, thanks for the help @michaela12

[mbain108]

Is this issue still open? If not, I would like to take a look at it.

[michaela12]

@mbain108 Hi, It's still open! So feel free to take a look at it!

[datapythonista]

yes, let us know if you need help @mbain108

[Jaisu-1]

Hi, can I take a look at this?

[WillAyd]

Go for it!

[MaxVanDeursen]

@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.

[datapythonista]

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.

[MaxVanDeursen]

@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.

[datapythonista]

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.

[MaxVanDeursen]

@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.

[datapythonista]

this is useful @MaxVanDeursen, can you create an issue in the ipython project then: https://github.com/ipython/ipython/issues and link it here.

[MaxVanDeursen]

Explicit xref: ipython/ipython#11606

Do you think that there's anything to be done until the issue is of IPython is ultimately fixed?

[datapythonista]

for what I understand, when the ipython directive is fixed, this will be resolved, nothing to do in our side

[DavidToneian]

I can't reproduce this on latest main on linux. Likely has been fixed?