56
Reading the Python Official Documentation is rugged (lemm.ee)
submitted 2 years ago by to c/python@programming.dev
28 comments fedilink hide all child comments
 

I am at a high-beginner/low-intermediate level in Python, and one thing that drives me nuts is how poorly I am able to read the Python official documentation and grok how to use the described code.

What's the secret? Are there any guides/videos/books that can help my understand how to approach reading it? Or, is it just one of those things that I need to just keep coming back to while coding, and eventually I will get the hang of it?

you are viewing a single comment's thread
view the rest of the comments
[–] 8 points 2 years ago (2 children)

What exactly is the issue? I think some modules are better than others. But, if the method says what its arguments are, what their types are, and what the return is, what's the issue?

Some things are more complex, and the docs I've used generally seem to be good about including examples. Like MagicMock. But, maybe if you gave an example of something you found hard to understand we could help?

  • permalink
  • fedilink
  • source
  • hideshow 4 child comments
    •
  • [–] 2 points 2 years ago* (last edited 2 years ago) (1 child)

    I've been generally happy with the documentation, but sometimes you need to see how something is supposed to be used.

    It's not the python documentation, but the Qt documentation (which is used to understand PyQt) where I wanted to play some video. Well, you need a QMediaPlayer to control the video. But the video apparently needs to be a QGraphicsVideoItem for the actual video, but wait that also has to be in something, Turns out you need to put it into a QGraphicsScene, which ALSO needs to be in a QGraphicsView. And it wasn't easy to find out, because some of these needed to take another item as init argument, while others needed to call a method to add them. So you are left to figure out what all these things are and what purpose each of them do differently, which order all should be created in, and try too keep track without messing up all the similar type names. One place where loosely typed python gets real weak. It's seemingly obvious from the way I wrote it though, but having just the video playback as my starting point, finding out what classes to use to begin with was hard.

    Another case isn't Python, but C#. Where some framework docs give class definitions but don't tell you that those are used to be "subclassed" to override a specific method and then the class is set as a property on a object you want behavior to change for, using a class name that really wasn't letting on what it was doing at all. This happened after ChatGPT came into existence, and it throw me a complete example. Other times tho, it makes up a similar thing.... which sucks

  • permalink
  • fedilink
  • source
  • parent
  • hideshow 2 child comments
    •
  • [–] 1 point 2 years ago (1 child)

    Well that's totally different. Last time I looked at pyqt, those docs were a nightmare. I would always go to the c++ docs.

    Same with any other random docs. They absolutely vary in quality and usefulness. But you were talking about the official python docs, no?

  • permalink
  • fedilink
  • source
  • parent
  • hideshow 2 child comments
    •
  • [–] 1 point 2 years ago

    My point was just, just input and output often isn't enough to tell you how to use something. Qt is an extreme example, but even the C++ docs leave how to use more complex objects out. Which makes em a pain to learn to use. I see some similar examples mentioned for the python docs here as well.

  • permalink
  • fedilink
  • source
  • parent