Could you please correct the URLs for the following:
As far as I remember, PHP does not support modules like Python does. Python’s modular nature lends itself well to documenting module functions together. I could provide more examples, but I’d need to know which module or function you have in mind. Alternatively, which module is lacking examples?
We could also go for a middle ground: one page per section. Some pages are just way too long.
That also makes editing them easier.
As someone who’s written lots of API docs, and authored a training
course or two (one for Python, even, though it was over 20 years ago):
coming up with examples that are short enough to be digestible and yet
meaningful and not just completely contrived… is actually The Hard
Part. Work like that has happening in a few places, it just takes
someone to show interest in a specific module and discuss improvements -
things have to happen bit by bit,. Guess I don’t feel like it gets us
much to just generically say “there should be more examples”, if that’s
the conclusion of this thread.
Exactly…
Yes, I should have been more creative and precise in the title, indeed. Regarding to what I mean, let me try to clarify, my main objective with this topic was to first understand the state of art of the python documentation, then propose the people (I’m volunteering myself) to add more examples in the Python documentation, if by doing so other people are suggesting improvements such as (split one function per page, allow comments, …) then let’s hear what everyone has to say, improving something that will help many people, it sounds like a good idea to me, if we have enough hands to do so let it be, however, it must be well discussed beforehand (As it was 15 years ago, I believe).
The first step is identifying what’s wrong with the current documentation format.
If you’re having trouble understanding the current documentation format, just move this thread over to Help.
Documentation formats really depend on the technology being documented.
It’s unclear what this thread is proposing. If it’s about adding more examples, you’ll need to demonstrate that the documentation lacks sufficient examples. If it’s about changing the documentation format, you’ll need to identify what’s wrong with the current format, and so on.
I can’t edit the url as somehow I can’t edit my post! Regarding providing more examples, thanks for be willing to do so, there are several, I will however get this topic from this forum as an example of a few improvements in examples that might help someone: The Documentation for PyList_GetSlice could provide example usage - #2 by kknechtel
In regards of you find sufficient or not the amount of examples in the docs, usually more experienced developers in Python won’t have a lot of problems finding themselves a way out, however beginners and a few intermediate devs might struggle for a while, thus having a workable example could be a good idea.
Beginners should start with tutorials (and skim over the glossary):
Usually, if a function has no example, a similar example is provided in the tutorials or for a similar function. If not, then there are insufficient examples. That’s what needs to be proven before adding another example.
I don’t know how often this comes up, but it’d be nice to link to the example in the tutorial from the relevant API doc. Or even just show the same example again, if there’s a way to do that without keep two copies (to ensure it is always synchronized).
As long as the examples are clear and useful (not trivial, as @mwichmann described), it’s fine have lots of extras. The problem is writing them.
Perhaps we’re experiencing the cognitive bias known as the Curse of Knowledge, and I genuinely want to identify what’s lacking in the current documentation.
For example, in my opinion, an example isn’t necessary for the function discussed at: The Documentation for PyList_GetSlice could provide example usage
Depending on how exactly the pages end up looking, too many examples or too large examples could make the API pages way harder to read, making the information I actually need harder to find. I think a few more examples wouldn’t hurt on most pages, but I wouldn’t say more examples are always better.
In an extreme formulation, which I only somewhat agree with, the need to add examples indicates bad API design. Good design should make how to use a function/class be obvious for people with the required background information, and this background information should be provided by e.g. the module introduction. Ofcourse, in practice, this is an impossible standard to reach, even ignoring backwards compatibility, so adding examples is a good idea.
How about:
These pages are by far the largest (211 and 198 KB respectively). I’m wondering if we could split these up in sub pages.
I guess I should have added the shouldn’t-be-necessary “and it’s implemented well” caveat. I thought “clear and useful” was enough but apparently not. 
If the pages end up so cluttered that the API is hard to read, that’s a page design problem, not a “too many examples” problem. It’s 2024, we have the technology to do this:
foofoo is a builtin function to foo a bar, and maybe baz
If you just forgot the signature: it’s foo(bar, baz=False)
Examples 1…3
Examples 4 … 10
Examples 11 … 100
This is now starting to be bike shedding, but I don’t think collapsible regions solve this problem. I just opened all your sections just in case there was something interesting in there. The same will happen on docs pages.
CTRL+F search in page is also problematic: Either it’s going to search through all the examples, making them just as annoying as before (although for a slightly smaller set of situations), or they are going to be ignored, in which case I might miss important examples.
Sure, that’s not an ideal design, it was just trivial to demonstrate in a Discourse post.
Another way to frame this is through the Diátaxis framework: examples are on the Tutorial/How-To side, API is on the Reference side. I think the best documentation keeps them separate but also makes it easy to move between them without getting lost. e.g. if I’m reading a reference and think “wait, but what does this look like in practice?” I want to jump to an example and then back again.
The way documentation is often written, the writer is trying to guess when people will need an example, and insert it when appropriate–which leads to this tradeoff for different readers.
None of this is to say that it’s easy to write the ideal documentation, far from it. I’m just thinking out loud about how it might be possible to reconcile the issues here.
Yep, that is something I agree with. But it crucially means that just adding examples to the docs page (the most straightforward way of “solving” the original request in this thread) goes against this (presumably good) design, which is my point, but better expressed :-) [1]
Man; I really can’t convince discourse from leaving my emoticons alone without putting them in code blocks :-( ↩︎
Just noting that the Python Library Reference is already over 2500 pages in PDF. This might be overwhelming even for a seasoned user.
Skimming over it, you can find plenty of usage examples that are not trivial for a casual user:
import gzip
import shutil
with open('example.txt', 'rb') as f_in:
with gzip.open('example.txt.gz', 'wb') as f_out:
shutil.copyfileobj(f_in, f_out)
…but you wouldn’t miss much because you can:
import gzip
with open('example.txt', 'rb') as f_in:
with gzip.open('example.txt.gz', 'wb') as f_out:
while True:
chunk = f_in.read(1024)
if not chunk:
break
f_out.write(chunk)
However, using shutil.copyfileobj is a helpful example. These examples promote the use of standard libraries well. Note that shutil.copyfileobj lacks an example in its module documentation.
I’m trying to be concise and draw a conclusion here, thus here it is what I’ve got so far.: It doesn’t seem we have a consensus about split of the pages, but it seems everyone is against allowing comments. And it seems the majority of the people agree with one single change: “Add more examples, in the docs”, and the last question remaining is: Where do we add the examples? How many functions are missing examples?
That is almost status quo.
Note that some functions does not need any example. There are many cases where an example is redundant:
As I mentioned in my previous post, shutil.copyfileobj lack an example in its module documentation. Why? Because it’s not possible to demonstrate it, you need two open two files and practice it by yourself.
Simple Boolean Functions
…
Wrapper Functions
…
Alias Functions
…
Getter and Setter Methods
…
…
Also, I (we) don’t consider an example a simple function call like value = func(param1, param2). That is not helpful.
If you find a one-liner example, its purpose is to demonstrate a concept not related to the language itself. For example, fmean([3.5, 4.0, 5.25]) . However, it is not going to help if you lack the necessary background in statistics. That is more related to the mathematical style of teaching, rather than the documentation format.
I too missed PHP’s one-function-per-page documentation when I first learned Python, though PHP has/had the “advantage” of a single massive top-level namespace of functions, which makes such an approach more viable.
I wonder if it’s possible to add a new Sphinx HTML target that generates a page per defined python ref that includes just the docs from the .. func:: / .. class:: / whatever, with a prominent banner at the top saying
This is a snippet of
object.__new__documentation. Click here to see the snippet in context
It might help with SEO? Certain official Python method documentation is almost ungoogleable at the moment, __init__ being the most recent example I have to hand.
For the record I am not volunteering to do this work 