Mailman 3 August 2017 - docs

[issue31024] typing.Tuple is class but is defined as data inside https://docs.python.org/3.6/objects.inv
by Guido van Rossum Aug. 23, 2017

Aug. 23, 2017

Guido van Rossum added the comment: OK, I think Sphinx is way too complicated for its own good, and it's arguably not the fault of Python's documentation that this doesn't work for you. I would like to close this issue as "won't fix", except... in a sense Tuple actually *is* a class, since you can subclass from e.g. Tuple[int, str]. @Levikvskyi, what do you think? ---------- _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue31024> _______________________________________

1 0

[issue31024] typing.Tuple is class but is defined as data inside https://docs.python.org/3.6/objects.inv
by Bernát Gábor Aug. 23, 2017

Aug. 23, 2017

Bernát Gábor added the comment: I suppose when the python.org documentation is generated the objects.inv file gets generated with it (I did not found exactly this piece of code here though). When Sphinx runs, it's intersphinx plugin goes out to python.org, downloads the objects.inv, decodes it, and then tries to map the docstring param/return values/references to URLs. Actually intersphinx does not make the deduction of the type. It uses what the users entered in the docstring. In this case the user needs to know for each element to which bucket has been assigned to (e.g. class/data/function/method/exception/macro); and for compatibility reason that needs to stay stable, otherwise with a Python upgrade the user would need to update the code of its docstrings. That being said for the sake of automation, in my case there actually another sphinx plugin (https://github.com/agronholm/sphinx-autodoc-typehints/blob/master/sphinx_au…) which actually generates, on the fly, the type information. So I suppose as a fix for my problem the sphinx_autodoc_typehint could be altered to still give back data, even though this now is a class. I'm not sure though how confident I am on "lying" to users about the data/class; but I suppose it's a necessary evil at this point. So should we keep everything as it is? When I first identified why Tuple does not have the URL mapped to it, I thought the problem to be the fact that it goes to the wrong bucket (by just inspecting its type): data; but now I see that may not be such a bad thing after all. ---------- _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue31024> _______________________________________

1 0

[issue12887] Documenting all SO_* constants in socket module
by Sandro Tosi Aug. 22, 2017

Aug. 22, 2017

New submission from Sandro Tosi <sandro.tosi(a)gmail.com>: spinning off msg142613 - it would be interesting to have in the socket module documentation also an explanation of all the several SO_ flags available; even a compact table could be ok; or even a link to a remote reference for them. ---------- assignee: docs@python components: Documentation messages: 143428 nosy: docs@python, eric.araujo, ezio.melotti, sandro.tosi priority: normal severity: normal stage: needs patch status: open title: Documenting all SO_* constants in socket module versions: Python 2.7, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue12887> _______________________________________

5 5

[issue31262] Documentation Error
by Dipti Sherlekar Aug. 22, 2017

Aug. 22, 2017

New submission from Dipti Sherlekar: Documentation says : In C++ terminology, normally class members (including the data members) are public Solution: In C++ the class memebers are private not public by default. ---------- assignee: docs@python components: Documentation messages: 300727 nosy: Dipti Sherlekar, docs@python priority: normal severity: normal status: open title: Documentation Error versions: Python 3.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue31262> _______________________________________

3 3

[issue31024] typing.Tuple is class but is defined as data inside https://docs.python.org/3.6/objects.inv
by Guido van Rossum Aug. 22, 2017

Aug. 22, 2017

Guido van Rossum added the comment: Thanks, I am a little closer to understanding now. > once intersphinx looks at the Tuple during documentation generation it deduces it actually is of type class How does intersphinx deduce this? Also, does it run when we generate the Python docs, or when you generate the docs for your project (that references the Python docs)? Finally, are there other objects in the typing for which this is a problem? (I guess I could answer this myself once I understand how intersphinx decides whether something is a class or data.) I also think this is somewhat unfortunate, because it seems that whenever something is changed from "class" to "data" or vice versa, intersphinx will be confused, even though it's easy to give examples where such a change could be backwards compatible. ---------- _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue31024> _______________________________________

1 0

[issue31024] typing.Tuple is class but is defined as data inside https://docs.python.org/3.6/objects.inv
by Ivan Levkivskyi Aug. 22, 2017

Aug. 22, 2017

Ivan Levkivskyi added the comment: > For the end user the fact that this is a class is still hidden I am not sure what you mean by this, but with your PR the rendered docs will literally say ``class typing.Tuple``. > We should probably add a unit test that makes sure all runtime "type" matches with documentation "type" in the future I already mention, this was not an omission but a deliberate decision, see http://bugs.python.org/review/28644/diff/19105/Doc/library/typing.rst#newco… (and below the same for Callable) ---------- _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue31024> _______________________________________

1 0

[issue31024] typing.Tuple is class but is defined as data inside https://docs.python.org/3.6/objects.inv
by Bernát Gábor Aug. 22, 2017

Aug. 22, 2017

Bernát Gábor added the comment: so here's the problem in detail: Intersphinx (http://www.sphinx-doc.org/en/stable/ext/intersphinx.html) is a built in Sphinx plugin that allows to link to documentation of other projects in your own documentation. For example when specifying the argument of a function which can be either int or string you might specify the argument to be Union[int, str]. In this case Sphinx will generate the type of the argument as this object, where e.g. the Union word will be a link to https://docs.python.org/3/library/typing.html#typing.Union and so on. In order to know for which object/function/type what is the correct URL an intersphinx object (which is basically a mapping) needs to be generated. This maps each element to an URL. This intersphinx mapping storage object (available at https://docs.python.org/3/objects.inv and similarly under other version pattern for the according version) is generated from the Python documentation. Now there's one indirection as far as this objects.inv goes; it does not actually stores mappings of element to URL, but what instead does it stores a mapping of type to element to url. Where type is here defined as either data/class etc. In order to resolve from an element to an URL both keys need to be correct (the type and the key too). For Python 3.6+ the typing.Tuple mapping now fails because according to the documentation the Tuple is under the section data, but once intersphinx looks at the Tuple during documentation generation it deduces it actually is of type class, and tries to locate it there. In order for intersphinx to resolve the correct web page URL, the runtime information of an element need to coincide with it's documentation type. Hence, what this PR tries to fix, migrating the documentation type/section of data to class (as in the meantime under Python 3.6 the Tuple is now a class). For the end user the fact that this is a class is still hidden, but for the documentation generation tool to resolve the correct URL, the runtime information needs to coincide with the documentation one. We should probably add a unit test that makes sure all runtime "type" matches with documentation "type" in the future. Let's make that the scope of another PR; is now clear? ---------- _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue31024> _______________________________________

1 0

Misnomer on webpage
by hyphen point Aug. 22, 2017

Aug. 22, 2017

https://docs.python.org/3.5/tutorial/stdlib.html I might be wrong (English is not my mother-tongue) but in the following sentence in section 10.1 seems to be an error. The built-in dir() <https://docs.python.org/3.5/library/functions.html#dir> > and help() <https://docs.python.org/3.5/library/functions.html#help> functions > are useful as interactive aids for working with large modules like os > <https://docs.python.org/3.5/library/os.html#module-os>: Shouldn't the plural of aide be aides? Greetings, Mat

1 0

[issue31024] typing.Tuple is class but is defined as data inside https://docs.python.org/3.6/objects.inv
by Guido van Rossum Aug. 22, 2017

Aug. 22, 2017

Guido van Rossum added the comment: Before I spend more time reviewing your patch, can you please explain what you mean by "sphinx fails to find these"? Is there a particular dead link on docs.python.org or a specific query you typed in the search box that failed to find the definition of typing.Tuple? ---------- _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue31024> _______________________________________

1 0

[issue31024] typing.Tuple is class but is defined as data inside https://docs.python.org/3.6/objects.inv
by Roundup Robot Aug. 22, 2017

Aug. 22, 2017

Changes by Roundup Robot <devnull(a)psf.upfronthosting.co.za>: ---------- pull_requests: +3219 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue31024> _______________________________________

1 0