PEPs should be included with the documentation download

[Aseem Bansal]

Currently the documentation download includes a lot of things but PEPs are not its part. I wanted to suggest that PEPs should be included in the download. They are very much relevant to Python.

 

[Chris Angelico]

Currently the documentation download includes a lot of things but PEPs are not its part. I wanted to suggest that PEPs should be included in the download. They are very much relevant to Python.

The PEPs are kinda like the specs that Python is built from, rather
than being end-user documentation; certainly most, if not all, are
unnecessary to most use of Python. There's really no point downloading
a whole pile of rejected PEPs as part of the crucial user-facing docs.

Also, how many people actually depend on the downloadable
documentation, rather than simply reading things online?

ChrisA

 

[random832]

The PEPs are kinda like the specs that Python is built from, rather
than being end-user documentation; certainly most, if not all, are
unnecessary to most use of Python. There's really no point downloading
a whole pile of rejected PEPs as part of the crucial user-facing docs.

Also, how many people actually depend on the downloadable
documentation, rather than simply reading things online?

If you've taken your laptop to somewhere there's no wi-fi, it's nice to
have offline help.

I think, though, that if there's any useful information that can be
obtained by reading accepted PEPs but not the documentation, or if
things are explained less clearly than in the PEPs, that's a bug in the
documentation, and should be remedied by adding to the documentation.

 

[Jerry Hill]

I think, though, that if there's any useful information that can be
obtained by reading accepted PEPs but not the documentation, or if
things are explained less clearly than in the PEPs, that's a bug in the
documentation, and should be remedied by adding to the documentation.

Personally, the only PEPs I've used as reference material as PEP 8
(the Python Style Guide), and PEP 249 (the Python Database API
Specification v2.0). If I recall correctly, one of the database
adapters I used basically said that they were PEP 249 compliant, and
didn't have much documentation beyond that.

It seems to me that adding the PEPs to the compiled documentation
would be a good thing. They are at least as useful as the Language
Reference or the Embedding and Extending Python sections that are
already included.

 

[random832]

Personally, the only PEPs I've used as reference material as PEP 8
(the Python Style Guide), and PEP 249 (the Python Database API
Specification v2.0). If I recall correctly, one of the database
adapters I used basically said that they were PEP 249 compliant, and
didn't have much documentation beyond that.

Maybe there should be documentation for PEP 249 and other such "API
Specifications" in the main documentation tree, in the same way that
..NET documents interfaces.

 

[Chris Angelico]

Personally, the only PEPs I've used as reference material as PEP 8
(the Python Style Guide), and PEP 249 (the Python Database API
Specification v2.0). If I recall correctly, one of the database
adapters I used basically said that they were PEP 249 compliant, and
didn't have much documentation beyond that.

It seems to me that adding the PEPs to the compiled documentation
would be a good thing. They are at least as useful as the Language
Reference or the Embedding and Extending Python sections that are
already included.

Ah, yes, there are a few that would be good. But I don't really see
that all the internally bits (PEP 393, anyone?) and rejected proposals
(PEP 315) need to be in the download. I wouldn't expect the full set
of RFCs to be included with the docs for the socket module, so I
equally don't expect the PEPs to be included.

ChrisA

 

[Terry Reedy]

The PEPs are kinda like the specs that Python is built from, rather
than being end-user documentation; certainly most, if not all, are
unnecessary to most use of Python. There's really no point downloading
a whole pile of rejected PEPs as part of the crucial user-facing docs.

The manuals are intended to document current reality. Accepted PEPs
document plans, often minus details. They do not get updated to reflect
the initial implementation, let alone subsequent changes. Thus even

There are a few chapters in the manual that reference a PEP, either
because the details are though to be too esoteric for the manual or
becuase no one has yet gotten around to rewriting the material for the
manual. (In the latter case, a patch should be welcome.) So there might
be a reason to include a '(Highly) Selected PEPs' heading to the main
page. PEP 8 might be a candidate, though it was originally intended as
an internal style guide for the stdlib only.

 

[Dennis Lee Bieber]

I think, though, that if there's any useful information that can be
obtained by reading accepted PEPs but not the documentation, or if
things are explained less clearly than in the PEPs, that's a bug in the
documentation, and should be remedied by adding to the documentation.

The only PEP I routinely reference is the one covering the DB-API (2).
Since many of the DB adapters are supposed to follow it, and may actually
slough off documentation to that PEP.

 

[Aseem Bansal]

I do depend on offline documentation. I have both Python2 and 3's documentation offline. A lot of people have 24-hour access to internet but a lot of people don't have. And while moving around it isn't always possible to haveinternet then offline documentation is really helpful.

 

[Aseem Bansal]

I think, though, that if there's any useful information that can be
obtained by reading accepted PEPs but not the documentation, or if
things are explained less clearly than in the PEPs, that's a bug in the
documentation, and should be remedied by adding to the documentation.

PEP8 is referenced a lot but only a very small portion is included in the documentation (in the tutorial). I am a Python newbie and there may be other PEPs usually referenced which I might not be aware about.

Maybe add selected PEPs to the documentation? I agree that adding rejected PEPs is no good but there may be PEPs worthy of addition to the documentation.

 

[Terry Reedy]

I do depend on offline documentation. I have both Python2 and 3's documentation offline. A lot of people have 24-hour access to internet but a lot of people don't have. And while moving around it isn't always possible to have internet then offline documentation is really helpful.

If you have mercurial installed, you can easily download a read-only
clone of the peps repository (hg.python.org/peps, I believe). You can
even pull updates whenever you feel like it.

One can also clone the main repository and build the regular docs,
including the html version thereof. Again, pull and rebuild when you
expect to be offline.

 

[Chris Angelico]

Many countries do not have infrastructure that allows reliable, fast,
low-latency internet access 24-hours-a-day. Most countries's internet
infrastructure, in fact, does not satisfy all of those.

I'm aware of that. However, I'm also aware that many people still read
things online, even with a less-than-reliable internet connection.
Hence the question: How many people actually do use the downloaded
docs? Maybe it'd turn out to be quite high, but it's not an
unreasonable question.

ChrisA

 

[Ned Deily]

I think it's an unreasonable question. What would you accept as an
answer? Who could possibly be autoritative at estimating such a number?
How would you choose between competing authorities and estimates?

It should be sufficient to realise that the reality of internet
infrastructure in most countries makes it preferable – at least some of
the time, for some significant, even if small, number of users – to read
the documentation on local storage instead of on the internet.

In any case if you want to see this happen, someone needs to open an
issue and make a case for it on the Python bug tracker.

 

[Neil Cerutti]

I'm aware of that. However, I'm also aware that many people
still read things online, even with a less-than-reliable
internet connection. Hence the question: How many people
actually do use the downloaded docs? Maybe it'd turn out to be
quite high, but it's not an unreasonable question.

I use the compiled html/windows help and the integrated with the
interpreter html version of the Python docs, both downloaded and
installed for easy access.