It looks like sphinx.ext.autodoc has become the de-facto standard for "JavaDoc"-like comments in Python doc strings.
Sphinx is used to generate the docs at docs.python.org. But does it read the docstrings from the Python source .py files (using autodoc) to present on docs.python.org?
The library section of the docs includes method-by-method summaries, but these appear seamless with the text. Are they up-to-date with the comments in the source code?
In other words, is there a place I can go in the documents to find exactly the same text (formatting aside) as consulting the docstrings from the interpreter?
I haven't been able to find such a place yet. For example, looking at the docstring for print with the help mechanism yields:
>>> help(print)
Help on built-in function print in module builtins:
print(...)
print(value, ..., sep=' ', end='\n', file=sys.stdout, flush=False)
Prints the values to a stream, or to sys.stdout by default.
Optional keyword arguments:
file: a file-like object (stream); defaults to the current sys.stdout.
sep: string inserted between values, default a space.
end: string appended after the last value, default a newline.
flush: whether to forcibly flush the stream.
And when I look up print in the 3.6.2 docs (same version as used above), I find different documentation for print without any parameter-by-parameter description:
print(*objects, sep=’ ‘, end=’\n’, file=sys.stdout, flush=False)
Print objects to the text stream file, separated by sep and followed by end. sep, end, file and flush, if present, must be given as keyword arguments.
All non-keyword arguments are converted to strings like str() does and written to the stream, separated by sep and followed by end. Both sep and end must be strings; they can also be None, which means to use the default values. If no objects are given, print() will just write end.
The file argument must be an object with a write(string) method; if it is not present or None, sys.stdout will be used. Since printed arguments are converted to text strings, print() cannot be used with binary mode file objects. For these, use file.write(...) instead.
Whether output is buffered is usually determined by file, but if the flush keyword argument is true, the stream is forcibly flushed.
Changed in version 3.3: Added the flush keyword argument.
