I’d like to start my post with the following phrase: “…Python’s documentation has long been considered to be good for a free programming language…” (devguide.python.org).
I understand that the documentation is open-source and free of use, I also acknowledge the fact that the Python docs is ok, however, I believe it can be excellent, therefore I took the example from the php.net where every single function has an obvious explanation and a few good examples underneath it, I believe it’s time to borrow the idea.
3 Likes
Sounds great, where do you plan to start? 
3 Likes
Today, can I? I thought it was maintained by a set group of people.
There is a documentation team but I’m sure they’d be happy to get more volunteers.
To be a little more concrete: you can discuss ideas in the documentation section of this forum, and propose improvements on GitHub. I’m not sure which functions you feel need more documentation, but you can certainly propose improvements.
1 Like
I don’t see any example and the link in to the php version log and stuff, no example.
There was a discussion perhaps 15 years ago about adopting the doc style of some other language that let users directly add comments and examples to docs. I believe but am not sure it was php. In any case, the php example looked awful to me and others and the suggestion was rejected. We are pretty sparing with examples.
I believe someone once started a website to document functions by use examples. I could not find it now. Searching python by example returns sites with lots of example functions, as opposed to lots of example uses of builtin functions.
I do however, believe in learning how functions behave to trying them out with multiple arguments. This include passing things you think might raise. I am not sure if reading dozens of examples someone else tried is even close to doing it oneself. Interactive python is a tremendous tool for active learning.
1 Like
The ONLY reason to EVER read the comments section on the PHP docs is morbid curiosity. I think there’s a reason most languages don’t support that.
Python already does this in the bulk majority of its reference documentation
You linked the Python Development Guide (devguide.python.org) but miscalled it Python Documentation (docs.python.org). Note the first is for contributors of the Python language, the second is for Python users.
2 Likes
I think there’s a little misunderstanding here, Bruno quoted the devguide’s docs page which starts with this phrase:
1 Like
This sounds great, and this thread will be a good place to discuss the details of the changes you are considering. You don’t mention them explicitly, but there are a few big differences between the PHP docs and the Python docs:
- PHP tends to have one function per page. Python leans to a module per page.
- PHP allows user comments on the page.
I interpreted your suggestion to include the first change (one function per page) but not the second. Perhaps you didn’t even mean to include the first.
As to how to start, clarifying the changes here is the first step. If you want to add more examples to existing pages, that could be done with pull requests. If you want to split the Python pages into one function per page, that’s a big change that would require much more thought, discussion, and planning. If you want to add commenting to the pages, I think it’s a quick “no” :).
4 Likes
FYI that is also how the numpy documentation is organized (see Array creation routines — NumPy v1.26 Manual for example). What I like a lot is the list with a short description, which gives the available API at a quick glance. It’s very useful both for modules and classes.
With the current documentation, I have to scroll the whole page to know what functions are available. I find navigating huge pages a hassle (see for example Built-in Types — Python 3.12.3 documentation).
Instead of rewrinting the whole documentation, I think a first step would be to add pages using sphinx.ext.autosummary, which would link to the existing documentation. I tried to generate those automatically by my result was not that great.
Some module docuemntations already include such tables in the introduction, maybe this could be generalized ? See statistics — Mathematical statistics functions — Python 3.12.3 documentation.
I think there are multiple ways to improve the status quo, with different levels of implication and rewriting. I just listed some of them here, I can try to add more details if needed.
4 Likes
There are several examples throughout the documentation on php.net, only a few there is no example whatsoever.
I got your point, but the idea has nothing to do with allowing comments in the docs, I also don’t think this is the way. Regarding the 15 years old discussion, well, as you said, it was a long time ago, it might be a good moment to rethink about it and consider whether or not it worths the change. The fact that you believe that learning by trying out is respectful however with some additional examples you could save some time on this try and error approach.
I’m afraid I will have to disagree with you, by just navigating to the links which you shared, one can see that the majority is not covered by examples (Even dare to say that there are missing “good” examples.
Hi, actually I quoted the devguid.python.org only to reference the previous phrase copied from there, but this topic is related to the https://docs.python.org/
1 Like
You raised a very good question, should we have indeed 1 function per page? I’m fine with it, but I just wanted to at least add some good example in each function or at least in the majority of them.
And no, I’m not in favour of having comments in the docs either!
1 Like
Thanks, you just expanded a little bit better what I tried to explain! That’s the idea!
FYI that is also how the numpy documentation is organized (see
Array creation routines — NumPy v1.26 Manual for
example). What I like a lot is the list with a short description, which
gives the available API at a quick glance. It’s very useful both for
modules and classes.
A leading (or off to the side) list with short descriptions is nice.
But…
With the current documentation, I have to scroll the whole page to know what functions are available. I find navigating huge pages a hassle (see for example Built-in Types — Python 3.12.3 documentation).
Whereas I have a vehement dislike of one function per page. There’s an
index down the side of each module to link to individual functions or
classes or sections. And there’s always the page search, not to mention
the main index.
The numpy functions are often technically precise, and indeed often have
good examples.
This is an inherent problem with titling your thread “borrow [an] idea from PHP”. People will look at the PHP docs and the Python docs, and have to guess at which difference you’re advocating for.
Are you advocating for a “one function per page” model, or for more examples? Both are plausible improvements, although personally I’m not a fan of one func per page as it makes for an awful lot of clicking. Or putting it another way: breaking out functions into their own pages is really depriving the landing page of information, since you are going to have to start with the page that has almost no information, and then click through to the page that has information. Not a fan of that.
1 Like
Agreed it’s hard to tell what the actual proposal is here. FWIW, I’m -1 on one function per page, but perfectly happy with more examples (I can’t honestly see why anyone would object to having more examples).
1 Like
On principle? No, I doubt anyone would object. But someone has to actually write them. So if the OP’s offering to contribute some examples, that’ll definitely be listened to.