4 ms·

I almost feel like it's a python specific issue. No other eco system have I've had to scour so many random almost identical looking websites to learn the librar

I almost feel like it's a python specific issue. No other eco system have I've had to scour so many random almost identical looking websites to learn the libraries I use. Almost like spending lots of time making a documentation page is a rite of passage for python devs. Of course, some of it may be that I didn't need it as much for when I did java dev. Typing+docstrings help much more in the IDE than for python code. Also, it's good that most python devs want to document their code. I'd just wish they'd do a better job, and not be so inspired by the crappy official docs.

number6 4y ago
There is this tool: sphinx. Helps you making documentation + website. Can read you code and document it with your docstrings. Generates some okish documentation and is kind of boilerplate if you create a library. There do all these websites come from.
- vladvasiliu 4y ago
  Sure, for example Rust has rustdoc that does the same thing, but there's a common repository for documentation, kind of like pip is a common repository for libs in Python. There are connectors for ReadTheDocs to generate the Sphinx docs from GitHub, and probably from elsewhere, too. Yet many projects prefer to host the docs on some random domain.
  - formerly_proven 4y ago
    > Yet many projects prefer to host the docs on some random domain. The overwhelming majority of Python projects (and many non-Python projects as well) host their documentation/website on projectname.rtfd.io
  - number6 4y ago
    Just think of it: You start your lib, it becomes fairly popular; you think wow this deserves its own domain. Now it's more like a chore than a pet project, plus no one donates to your awesome lib - yes you believe in OSS, but BigBuckCorp who is using your lib could at least chip in. It is all a drag now, so you decide to move on, you owe them nothing, and they are giving you nothing. So years later your credit card expires, and you have to update it to update the domain, and you will definitely do it if you come to it but not now. And it's gone. Screw this...
pastage 4y ago
I came from Python and C, for me Java has these issues. I almost never find what I want about java libraries, I waste a lot of time this way. I'm sure you could measure this, but I guess we are just used to read code in different ways.
creshal 4y ago
"Duck typed" languages like python always force you to check the documentation three times just to make sure the author doesn't believe that ducks bark, I don't see it ever getting better unless we move away from them entirely.
- stavros 4y ago
  Just use types. At this point it's "I don't like how the blunt edge of this knife won't cut well".
  - ahaferburg 4y ago
    And how do you tell that the library authors?
    - stavros 4y ago
      Pull request.
OJFord 4y ago
I heard (somewhere, can't recall where, maybe The Bike Shed podcast with original hosts) it summarised as something like 'python is documented, ruby is tested', (as in library code, not the language itself) which is obviously a ridiculous generalisation/hyperbole, but it does seem to hold somewhat true, that they do more (resp. less) of those things respectively.
aulin 4y ago
There's unfortunately a lot of SEO spam dressed as docs in the python world. Usually all you need is in readthedocs.
- kevin_thibedeau 4y ago
  If you're using Github you don't even need RTD. You can host a Sphinx site direct from GH without the sluggishness and theming of RTD.
dalanmiller 4y ago
Ruby I have found to be incredibly difficult in this regard as well.
ksaj 4y ago
It's been a Common Lisp problem forever. Go to Github and do a simple search just to see how many projects are nearing completion, but then dropped at some random point never to be touched again. The README.md is almost always impeccable, and go into great detail about the upcoming plans that were already dropped years ago. Real go-getters, that bunch. Even better, add "quantum" to your search, and nearly all of them that aren't from the well-known quantum compute companies are like that. They really stand out among their peers. In a laughable way. Lisp people can't resist getting into something, and then just turning away without notice when they realize they're in over their heads. How many Lisp "books" and "tutorials" are being written over decades now. Especially the quantum ones? Lisp "tutorials" are the worst because it is so obvious the writer is learning at the same time they're writing. You're basically learning their mistakes as verified gospel. Only once you get some experience, or a better course, do you realize how much those "toots" lead you astray. Even the YouTube Lisp courses that pretend they are complete aren't. They get about half way through, and then rush through a one pager on OOP programming to end it. Ridiculous. I love the Lisp language. I really dislike its "meh" culture.
- dotancohen 4y ago
  Thank you for posting this. Where, please where, should I be learning Lisp? I'm getting deeper and deeper into Org mode and with that the whole Emacs train.
  - ksaj 4y ago
    The most famous resource is also probably one of the best. Practical Common Lisp, by Peter Siebel. https://gigamonkeys.com/book/ https://gigamonkeys.com/book/ You can read it for free. But its such a good resource I bought a hard copy and keep it within reach at all times. I like to take notes in the columns, and mark up interesting things I know I'll have to review on occasion. Last year Peter tweeted out a teaser that he might add some new content to the book, as there has been a lot of progress since this was written. But it is in no way outdated as is.
    - dotancohen 4y ago
sph 4y ago
For some reason, many Python libraries use readthedocs.io, their documentation is sparse, very shallow and the API reference is left undocumented, that I'm usually displeased whenever I see that website and colour scheme. I know that I'm gonna be left wanting. Conversely, the Elixir documentation is so high quality that I'm put in a good mood whenever I land on their version of the documentation browser (generated by ExDoc). It's not the fault of readthedocs per se, I guess it's what most projects that want a barebones documentation site and call it a day use.
- rmbyrro 4y ago
  I actually find too much aesthetics work rather distracting. It's commonly used to divert attention from what really matters... So, I appreciate Python bare bones documentation. Easier to judge its true value.
- autophagian 4y ago
  I thought readthedocs was just documentation hosting? If I remember correctly, the actual documentation generation is done with Sphinx.
  - sph 4y ago
    I stand corrected, then my issues are with the incomplete Sphinx docs I often see shipping with Python libraries.
tuetuopay 4y ago
This is something that somewhat plages the Rust ecosystem, since the .rs tld exists. Thankfully, every single library in existence has its docs built automatically and sent to docs.rs, so you don't even need those lib's websites. They have a use when you follow the git tip to have docs from HEAD and not a release.
- chrismorgan 4y ago
  It amuses me that I’m implicated in two parts of your comment. 1. I was the first person to use a .rs domain for Rust stuff. I wrote a bit about doing so in https://chrismorgan.info/blog/introducing-teepee/ https://chrismorgan.info/blog/introducing-teepee/ (heading “Aside: registering .rs domains”). I never finished Teepee, and allowed teepee.rs to lapse (and it hadn’t actually been being used yet, anyway; I would also note that this was from before a lot of the infrastructure we take for granted today existed, including docs.rs). 2. Not every single library has its docs built automatically by docs.rs. For starters, not all crates are on crates.io: some deliberately stick with Git dependencies. But even of things on crates.io, docs.rs will fail to build some, normally due to packager error or some failed FFI linkage (for which the most common solution is to vendor a copy of the foreign library code, either opt-out or opt-in with an instruction for docs.rs to opt in), but it’s possible to deliberately thwart just the building of docs (or even just docs.rs) if you really want to, for which I present another of my transgressions: https://docs.rs/crate/u-plus/latest https://docs.rs/crate/u-plus/latest (source of the prevention: https://git.chrismorgan.info/u-plus/blob/HEAD:/src/lib.rs https://git.chrismorgan.info/u-plus/blob/HEAD:/src/lib.rs, lines 4–5).
josteink 4y ago
> Almost like spending lots of time making a documentation page is a rite of passage for python devs. To be fair Python doesn’t have a good story for declaring static types, IDEs which can guide you as a library-consumer, nor for storing inline documentation/code-doc alongside your functions or classes. And then all that stuff has to go elsewhere in order for the libraries to be usable.
- rat87 4y ago
  python supports type hints and IDEs can use those hints as well as document genration

number6 4y ago

There is this tool: sphinx. Helps you making documentation + website. Can read you code and document it with your docstrings. Generates some okish documentation and is kind of boilerplate if you create a library. There do all these websites come from.

vladvasiliu 4y ago
Sure, for example Rust has rustdoc that does the same thing, but there's a common repository for documentation, kind of like pip is a common repository for libs in Python. There are connectors for ReadTheDocs to generate the Sphinx docs from GitHub, and probably from elsewhere, too. Yet many projects prefer to host the docs on some random domain.
- formerly_proven 4y ago
  > Yet many projects prefer to host the docs on some random domain. The overwhelming majority of Python projects (and many non-Python projects as well) host their documentation/website on projectname.rtfd.io
- number6 4y ago
  Just think of it: You start your lib, it becomes fairly popular; you think wow this deserves its own domain. Now it's more like a chore than a pet project, plus no one donates to your awesome lib - yes you believe in OSS, but BigBuckCorp who is using your lib could at least chip in. It is all a drag now, so you decide to move on, you owe them nothing, and they are giving you nothing. So years later your credit card expires, and you have to update it to update the domain, and you will definitely do it if you come to it but not now. And it's gone. Screw this...

pastage 4y ago

I came from Python and C, for me Java has these issues. I almost never find what I want about java libraries, I waste a lot of time this way. I'm sure you could measure this, but I guess we are just used to read code in different ways.

creshal 4y ago

"Duck typed" languages like python always force you to check the documentation three times just to make sure the author doesn't believe that ducks bark, I don't see it ever getting better unless we move away from them entirely.

stavros 4y ago
Just use types. At this point it's "I don't like how the blunt edge of this knife won't cut well".
- ahaferburg 4y ago
  And how do you tell that the library authors?
  - stavros 4y ago
    Pull request.

OJFord 4y ago

I heard (somewhere, can't recall where, maybe The Bike Shed podcast with original hosts) it summarised as something like 'python is documented, ruby is tested', (as in library code, not the language itself) which is obviously a ridiculous generalisation/hyperbole, but it does seem to hold somewhat true, that they do more (resp. less) of those things respectively.

aulin 4y ago

There's unfortunately a lot of SEO spam dressed as docs in the python world. Usually all you need is in readthedocs.

kevin_thibedeau 4y ago
If you're using Github you don't even need RTD. You can host a Sphinx site direct from GH without the sluggishness and theming of RTD.

dalanmiller 4y ago

Ruby I have found to be incredibly difficult in this regard as well.

ksaj 4y ago

It's been a Common Lisp problem forever. Go to Github and do a simple search just to see how many projects are nearing completion, but then dropped at some random point never to be touched again. The README.md is almost always impeccable, and go into great detail about the upcoming plans that were already dropped years ago. Real go-getters, that bunch. Even better, add "quantum" to your search, and nearly all of them that aren't from the well-known quantum compute companies are like that. They really stand out among their peers. In a laughable way. Lisp people can't resist getting into something, and then just turning away without notice when they realize they're in over their heads. How many Lisp "books" and "tutorials" are being written over decades now. Especially the quantum ones? Lisp "tutorials" are the worst because it is so obvious the writer is learning at the same time they're writing. You're basically learning their mistakes as verified gospel. Only once you get some experience, or a better course, do you realize how much those "toots" lead you astray. Even the YouTube Lisp courses that pretend they are complete aren't. They get about half way through, and then rush through a one pager on OOP programming to end it. Ridiculous. I love the Lisp language. I really dislike its "meh" culture.

dotancohen 4y ago
Thank you for posting this. Where, please where, should I be learning Lisp? I'm getting deeper and deeper into Org mode and with that the whole Emacs train.
- ksaj 4y ago
  The most famous resource is also probably one of the best. Practical Common Lisp, by Peter Siebel. https://gigamonkeys.com/book/ https://gigamonkeys.com/book/ You can read it for free. But its such a good resource I bought a hard copy and keep it within reach at all times. I like to take notes in the columns, and mark up interesting things I know I'll have to review on occasion. Last year Peter tweeted out a teaser that he might add some new content to the book, as there has been a lot of progress since this was written. But it is in no way outdated as is.
  - dotancohen 4y ago

sph 4y ago

For some reason, many Python libraries use readthedocs.io, their documentation is sparse, very shallow and the API reference is left undocumented, that I'm usually displeased whenever I see that website and colour scheme. I know that I'm gonna be left wanting. Conversely, the Elixir documentation is so high quality that I'm put in a good mood whenever I land on their version of the documentation browser (generated by ExDoc). It's not the fault of readthedocs per se, I guess it's what most projects that want a barebones documentation site and call it a day use.

rmbyrro 4y ago
I actually find too much aesthetics work rather distracting. It's commonly used to divert attention from what really matters... So, I appreciate Python bare bones documentation. Easier to judge its true value.
autophagian 4y ago
I thought readthedocs was just documentation hosting? If I remember correctly, the actual documentation generation is done with Sphinx.
- sph 4y ago
  I stand corrected, then my issues are with the incomplete Sphinx docs I often see shipping with Python libraries.

tuetuopay 4y ago

This is something that somewhat plages the Rust ecosystem, since the .rs tld exists. Thankfully, every single library in existence has its docs built automatically and sent to docs.rs, so you don't even need those lib's websites. They have a use when you follow the git tip to have docs from HEAD and not a release.

chrismorgan 4y ago
It amuses me that I’m implicated in two parts of your comment. 1. I was the first person to use a .rs domain for Rust stuff. I wrote a bit about doing so in https://chrismorgan.info/blog/introducing-teepee/ https://chrismorgan.info/blog/introducing-teepee/ (heading “Aside: registering .rs domains”). I never finished Teepee, and allowed teepee.rs to lapse (and it hadn’t actually been being used yet, anyway; I would also note that this was from before a lot of the infrastructure we take for granted today existed, including docs.rs). 2. Not every single library has its docs built automatically by docs.rs. For starters, not all crates are on crates.io: some deliberately stick with Git dependencies. But even of things on crates.io, docs.rs will fail to build some, normally due to packager error or some failed FFI linkage (for which the most common solution is to vendor a copy of the foreign library code, either opt-out or opt-in with an instruction for docs.rs to opt in), but it’s possible to deliberately thwart just the building of docs (or even just docs.rs) if you really want to, for which I present another of my transgressions: https://docs.rs/crate/u-plus/latest https://docs.rs/crate/u-plus/latest (source of the prevention: https://git.chrismorgan.info/u-plus/blob/HEAD:/src/lib.rs https://git.chrismorgan.info/u-plus/blob/HEAD:/src/lib.rs, lines 4–5).

josteink 4y ago

> Almost like spending lots of time making a documentation page is a rite of passage for python devs. To be fair Python doesn’t have a good story for declaring static types, IDEs which can guide you as a library-consumer, nor for storing inline documentation/code-doc alongside your functions or classes. And then all that stuff has to go elsewhere in order for the libraries to be usable.

rat87 4y ago
python supports type hints and IDEs can use those hints as well as document genration