4 ms·

> Sphinx is basically `grep` for docs. I don't really need that, that's what `App site:textual.textualize.io` is for in DDG/Google Let's do a study and compare

> Sphinx is basically `grep` for docs. I don't really need that, that's what `App site:textual.textualize.io` is for in DDG/Google Let's do a study and compare Rich and Textual, which is based on Rich. Here's a Textual class: https://textual.textualize.io/reference/events/#textual.events.MouseCapture https://textual.textualize.io/reference/events/#textual.even.... I need to find what is MessageTarget, so after some futile ctrl-f'ing I copy-paste it into search field. Suggestions show barely related results, like a code listing and another unit that references MessageTarget. Hitting Enter just drops me not onto a search results page but onto a barely related page that does not document MessageTarget at all. Then I want to find out what Point is. I just go to Google for this. It shows me Geometry page, which seems related... Except it lands me at the top and do you know how many times "point" (and "pointer", "pointing", etc) are used on the page? Many times, which is why Google thinks it's probably the most related to Point. After a minute of ctrl-f'ing I find no docs for Point. Note that at this point I don't even know whether either MessageTarget or Point is documented at all. If they aren't, then what a great use of my time! Of course search engine doesn't have the slightest idea about what I need, it merely matches entered words. As you can see, search is the true grep for documentation that you are describing: dumb and barely useful by itself. Here's a Rich class: https://rich.readthedocs.io/en/latest/reference/console.html#rich.console.ConsoleOptions https://rich.readthedocs.io/en/latest/reference/console.html.... they didn't even describe each parameter, but if you want to find how to instantiate (and where to import from) a ConsoleDimensions it's one click away. Same for built-in types, thanks to Intersphinx (I guess when they stop relying on typing_extensions, Literal will be hyperlinked as well). RST nudges you towards explicitly denoting relationships between different parts of your documentation, because its default behavior is to treat a single backtick as a semantic identifier that signifies a particular unit, not just a random snippet of text. Whenever you use a backtick, it will warn you if you reference a nonexistent unit. Unlike dumb search, it actually knows what relates to what. If you think I diss the work creators put into the library--I don't, I'm just pointing out to you why cross-reference is useful, and I wrote my original comment about their decision of documentation builder since some of them are apparently on HN.

camgunz 4y ago
Hah well, I get what you're saying (I mean, I got it before this). It's not always easy to find what you're looking for in docs, and it sounds like you really look to cross-references to help you do that. My counterpoint here is the Google protocol buffers docs for Python [0]. Again I don't want to come down too hard on others' work, but just this front page isn't that helpful to me. For one, I don't need everything prefaced with `google.protobuf`, I know that's the package I'm looking at, and for another, the needless `google.protobuf` prefix and the attendant wrapping make the sections on the left really hard to scan. But let's get into a specific module: timestamp_pb2 [1]. There are a grand total of two cross-references that aren't to the Python docs (which are KeyError and bool, which like, not the most helpful of cross-references). That's not a great showing. If your argument here is that "RST nudges you towards explicitly denoting relationships between different parts of your documentation", I'm not seeing it, and I would guess these docs get a fair amount of traffic. --- My argument here is that you're seeing features in ReST, and extrapolating characteristics about ReST docs based on those features, while ignoring real-world considerations (like developer motivation, for one). I'm sure ReST has features that seem like they would encourage doc authors to use cross-referencing more. But the docs I use are barely cross-referenced, I use DDG/Google searches for this, and pragmatically I think this is the experience of most people. [0]: https://googleapis.dev/python/protobuf/latest/ https://googleapis.dev/python/protobuf/latest/ [1]: https://googleapis.dev/python/protobuf/latest/google/protobuf/timestamp_pb2.html https://googleapis.dev/python/protobuf/latest/google/protobu...

camgunz 4y ago

Hah well, I get what you're saying (I mean, I got it before this). It's not always easy to find what you're looking for in docs, and it sounds like you really look to cross-references to help you do that. My counterpoint here is the Google protocol buffers docs for Python [0]. Again I don't want to come down too hard on others' work, but just this front page isn't that helpful to me. For one, I don't need everything prefaced with `google.protobuf`, I know that's the package I'm looking at, and for another, the needless `google.protobuf` prefix and the attendant wrapping make the sections on the left really hard to scan. But let's get into a specific module: timestamp_pb2 [1]. There are a grand total of two cross-references that aren't to the Python docs (which are KeyError and bool, which like, not the most helpful of cross-references). That's not a great showing. If your argument here is that "RST nudges you towards explicitly denoting relationships between different parts of your documentation", I'm not seeing it, and I would guess these docs get a fair amount of traffic. --- My argument here is that you're seeing features in ReST, and extrapolating characteristics about ReST docs based on those features, while ignoring real-world considerations (like developer motivation, for one). I'm sure ReST has features that seem like they would encourage doc authors to use cross-referencing more. But the docs I use are barely cross-referenced, I use DDG/Google searches for this, and pragmatically I think this is the experience of most people. [0]: https://googleapis.dev/python/protobuf/latest/ https://googleapis.dev/python/protobuf/latest/ [1]: https://googleapis.dev/python/protobuf/latest/google/protobuf/timestamp_pb2.html https://googleapis.dev/python/protobuf/latest/google/protobu...