Documentation for local directory --index-url is inadequate

[mhsmith]

The --index-url documentation says its parameter "should point to a repository compliant with PEP 503 (the simple repository API) or a local directory laid out in the same format."

PEP 503 says that index directory URLs must "respond with a valid HTML5 page".

But what does it mean for a local directory to "respond with a valid HTML5 page"? #846 indicates that pip will look for an index.html file in the directory. But this is not documented anywhere.

[terrdavis]

Some other things that I learned via trial-and-error:

• On windows, to point to a unc-path, only this format works: --index-url=file:///\server\share (I would expect --index-url=file:///\\server\share to work too...)
• Also on windows, for a lettered drive, both of these work; I suspect the first is bug:
  • --index-url=file:/c:\dir1\dir2
  • --index-url=file:///c:\dir1\dir2

[mhsmith]

See also #5846.