Be explicit about leading * when documenting *args, **kwargs.

[Carreau]

This seem to be what most docstring involving args/kwargs are doing
including the example.py; Though I've seen other project be less
consistant, so make the suggestion explicit instead of letting users
infer from the example.

Other convention I've seen are:

• *xi , documented as x1,x2, ..., xn : type
• just the name without the leading */**.
• prefixing * with \\*.

[rgommers]

Will this render correctly? IIRC the backslashes are necessary, or they were at some point.

[Carreau]

Will this render correctly? IIRC the backslashes are necessary, or they were at some point.

I was unsure, but that seen to work for example.py in this repository, without warnings (it's a raw docstring though, but even without the r"" just the math is garbled):

$ make html
# These two lines make the build a bit more lengthy, and the
# the embedding of images more robust
rm -rf _build/html/_images
#rm -rf _build/doctrees/
sphinx-build -b html -d _build/doctrees  -nWT --keep-going . _build/html
Running Sphinx v3.0.1
loading pickled environment... done
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 0 source files that are out of date
updating environment: 0 added, 1 changed, 0 removed
reading sources... [100%] example
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] index
generating indices...  genindex py-modindexdone
highlighting module code... [100%] example
writing additional pages...  searchdone
copying static files... ... done
copying extra files... done
dumping search index in English (code: en)... done
dumping object inventory... done
build succeeded.

The HTML pages are in _build/html.

Build finished. The HTML pages are in _build/html.

https://docs.scipy.org/doc/scipy/reference/generated/scipy.spatial.distance.pdist.html also seem fine.

[larsoner]

Thanks @Carreau !