make.py --single with *.rst file unexpected behaviour.

[MaxVanDeursen]

Code Sample, a copy-pastable example if possible

When in the doc folder:

python make.py --single $(pwd)/source/development/contributing.rst
Running Sphinx v1.8.4
loading pickled environment... done
[autosummary] generating autosummary for: index.rst
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: [] 0 added, 1 changed, 0 removed
reading sources... [100%] index                                                                                                                                                      
/home/max/git/pandas/doc/source/index.rst:26: WARNING: toctree contains reference to nonexisting document 'home/max/git/pandas/doc/source/development/contributing'
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] index                                                                                                                                                       
generating indices... genindex py-modindex
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, 1 warning.

The HTML pages are in build/html.

Problem description

Although sphinx-build does exit correctly, no html file corresponding to the single required file is created in the build/html folder. The build/html folder is as follows:

.
├── genindex.html
├── index.html
├── objects.inv
├── py-modindex.html
├── search.html
├── searchindex.js
├── _sources
│   └── index.rst.txt
└── _static
    ├── ajax-loader.gif
    ├── banklist.html
    ├── basic.css
    ├── ...

The page opened in the web browser also gives back a 404.

From my first look around in make.py, I do not see anywhere where we are using the single parameter, except in the init function of DocBuilder. I will investigate further.

[MaxVanDeursen]

I now have found that this is not a bug, albeit a wrong documentation string once again. When using
python make.py --single development/contributions.rst instead, make.py does work correctly and a webpage is generated.

Should the documentation around the --single parameter be more explicit, or was I just stupid?

The two sections of documentation which I was able to find were:
make.py

  --single FILENAME     filename of section or method name to compile, e.g.
                        "indexing", "DataFrame.join"

Contribution guide

# section, that which is in indexing.rst
python make.py clean
python make.py --single indexing

[jreback]

hmm

@datapythonista @TomAugspurger

[TomAugspurger]

Probably update the documentation to specify that the filename should be relative to the main index.rst.

[MaxVanDeursen]

@TomAugspurger I'll be on that!