Repository: pandas-dev/pandas

Issue:
make.py --single with *.rst file unexpected behaviour.
#### 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.



Discussion:
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**](https://pandas-docs.github.io/pandas-docs-travis/development/contributing.html#building-the-documentation)
```# compile the docs with only a single
# section, that which is in indexing.rst
python make.py clean
python make.py --single indexing
```
hmm

@datapythonista @TomAugspurger 
Probably update the documentation to specify that the filename should be relative to the main `index.rst`.
@TomAugspurger I'll be on that!

Resolving patch:
diff --git a/doc/make.py b/doc/make.py
--- a/doc/make.py
+++ b/doc/make.py
@@ -294,14 +294,16 @@ def main():
                            help='number of jobs used by sphinx-build')
     argparser.add_argument('--no-api',
                            default=False,
-                           help='ommit api and autosummary',
+                           help='omit api and autosummary',
                            action='store_true')
     argparser.add_argument('--single',
                            metavar='FILENAME',
                            type=str,
                            default=None,
-                           help=('filename of section or method name to '
-                                 'compile, e.g. "indexing", "DataFrame.join"'))
+                           help=('filename (relative to the "source" folder)'
+                                 ' of section or method name to compile, e.g. '
+                                 '"development/contributing.rst",'
+                                 ' "ecosystem.rst", "pandas.DataFrame.join"'))
     argparser.add_argument('--python-path',
                            type=str,
                            default=os.path.dirname(DOC_PATH),


Test patch: