4 ms·

Yeah, I was struggling with this trend earlier when looking at the Textual library, which has amazing examples but doesn't seem to have very detailed full API d

Yeah, I was struggling with this trend earlier when looking at the Textual library, which has amazing examples but doesn't seem to have very detailed full API documentation. I wonder why this trend is happening, especially when python in particular has a bunch of standards and tools to make generating full API docs pretty straightforward.

nerdponx 3y ago
I think it's partly because Sphinx is clunky and people have been using MkDocs instead, which I believe either doesn't generate anything from docstrings at all, or didn't until recently. I don't know why they're not using Pdoc, maybe they don't know about it. I also get the sense that there is a growing movement among programmers that API reference documentation is useless, or not worth putting effort into, because it's possible to go out of sync with the code and "nobody reads that anyway". I've heard people say things like "if you're advanced enough to read reference documentation, you're better off just reading the source anyway." It seems to be rooted in some kind of combination of extreme cynicism, a distorted sense of how people who aren't raw beginners learn to do things, and of a kind of false minimalism, wherein API documentation is old fuddy-duddy stuff for Java and C++ developers, and the new friendly easy way is to just read the examples. Such libraries also seem to exhibit a poor separation of public and private interfaces, so maybe it's just a reflection of people being bad at designing libraries.
- fuzztester 3y ago
  Unfriendly and short-sighted (at least if you want your lib to be used, else why publish it?), is more like it.
  - nerdponx 3y ago
    But they spent hours writing all those examples. I think it's the opposite, it's a misguided attempt at being friendly. Short-sighted, I agree with.
    - fuzztester 3y ago
      Okay, I get you, and agree. Yes, friendly, but without thinking, at least some, at a higher level, what might be a better use of their (limited) time.
- benrutter 3y ago
  I think what you've said feels exactly right. Maybe a better Sphinx just needs to exist, it seems like pythons standards should make it pretty simple to write something where API documentation generation is so trivial there's no reason not to. I normally do end up reading source code, but it often introduces unnecessary hassle because while it's great for "what does this function do?" type of stuff, it really falls down when you want to know "what type of functions fall under this module" since you end up navigating up and down through a lot of imports that make sense for code organization but are abstracted away at the point of use.
- DandyDev 3y ago
  You can use the mkdocstrings plugin with mkdocs which will generate api docs from your functions and classes and their docstrings just like Sphinx does. It even supports inv files just like Sphinx so you can reference third party libraries in your own reference docs

nerdponx 3y ago

I think it's partly because Sphinx is clunky and people have been using MkDocs instead, which I believe either doesn't generate anything from docstrings at all, or didn't until recently. I don't know why they're not using Pdoc, maybe they don't know about it. I also get the sense that there is a growing movement among programmers that API reference documentation is useless, or not worth putting effort into, because it's possible to go out of sync with the code and "nobody reads that anyway". I've heard people say things like "if you're advanced enough to read reference documentation, you're better off just reading the source anyway." It seems to be rooted in some kind of combination of extreme cynicism, a distorted sense of how people who aren't raw beginners learn to do things, and of a kind of false minimalism, wherein API documentation is old fuddy-duddy stuff for Java and C++ developers, and the new friendly easy way is to just read the examples. Such libraries also seem to exhibit a poor separation of public and private interfaces, so maybe it's just a reflection of people being bad at designing libraries.

fuzztester 3y ago
Unfriendly and short-sighted (at least if you want your lib to be used, else why publish it?), is more like it.
- nerdponx 3y ago
  But they spent hours writing all those examples. I think it's the opposite, it's a misguided attempt at being friendly. Short-sighted, I agree with.
  - fuzztester 3y ago
    Okay, I get you, and agree. Yes, friendly, but without thinking, at least some, at a higher level, what might be a better use of their (limited) time.
benrutter 3y ago
I think what you've said feels exactly right. Maybe a better Sphinx just needs to exist, it seems like pythons standards should make it pretty simple to write something where API documentation generation is so trivial there's no reason not to. I normally do end up reading source code, but it often introduces unnecessary hassle because while it's great for "what does this function do?" type of stuff, it really falls down when you want to know "what type of functions fall under this module" since you end up navigating up and down through a lot of imports that make sense for code organization but are abstracted away at the point of use.
DandyDev 3y ago
You can use the mkdocstrings plugin with mkdocs which will generate api docs from your functions and classes and their docstrings just like Sphinx does. It even supports inv files just like Sphinx so you can reference third party libraries in your own reference docs