The README is a README, not really documentation -- to be honest I'd remove all the code from there entirely if it wasn't that the README is what's used for PyPI and is what you see when you load the repo, so it's *something* for someone to see. But beyond "show me what this library does in one sentence" I'd really expect someone to read the documentation.
You're not wrong, it's just that reality is a like that. What code snippets ones seems in the README is usually all your eyes have time to scan.
Granted, if the project is your main at-work project and quality is super important then it might be a different story. So often, it's just one of many projects and the thing you're using a library for might not be a critical thing so you're looking for a quick fix and that's what the code snippets in the README are for.
If you think there are dangers with skimming a snippet like that I would remove it replace it with a link into the "meat of the documentation".
Comment
The README is a README, not really documentation -- to be honest I'd remove all the code from there entirely if it wasn't that the README is what's used for PyPI and is what you see when you load the repo, so it's *something* for someone to see. But beyond "show me what this library does in one sentence" I'd really expect someone to read the documentation.
But will think about it.
Parent comment
It helps but I think it would still be a good idea to mention it in that first little code snippet in the README
Replies
You're not wrong, it's just that reality is a like that. What code snippets ones seems in the README is usually all your eyes have time to scan.
Granted, if the project is your main at-work project and quality is super important then it might be a different story. So often, it's just one of many projects and the thing you're using a library for might not be a critical thing so you're looking for a quick fix and that's what the code snippets in the README are for.
If you think there are dangers with skimming a snippet like that I would remove it replace it with a link into the "meat of the documentation".