Comment by throwaway290 | Hacker News Reader

Comment by throwaway290 | Hacker News Reader

Parent Full thread

> I wrote a ton of Sphinx years ago and couldn't even tell you where to start today, but I'm fluent in Markdown because I use it everywhere.

You probably want to compare RST vs. Markdown, or Sphinx vs. MkDocs. Markup language and documentation builder are apples to oranges.

> Looking through the Textualize docs [0], they seem pretty good to me? It reminds me of most of the web UI toolkits I've used: components on the left, specific functions of the component you're viewing on the right. I think the advantages to Sphinx you're pointing out aren't super relevant to Textualize.

I looked at them before I wrote my original comment. They are not bad and they follow the tutorial/topic/reference pattern as Django does. But again they don't export a Sphinx inventory so I cannot cross-reference their units in some Python project I might work on that has Textual as a dependency; their own units are barely cross-referenced within the docs (e.g. they write `App` while in RST it'd be invalid, you'd use :class:`app.App` and it'd be automatically linked to unit's docs or you have to be explicit you want a dumb code snippet with ``App``); they don't link to source code, etc.

> but most people just add bare minimum docstrings and leave you to figure out the rest

Yes, it's definitely up to documentation writers in the first place. You can use Sphinx and have bad docs.

> On the contrary, I think something that does help you generate better ones is liking your doc tool. If you're not into Sphinx, you're not gonna be enthused about writing excellent docs in it. If you're into mkdocs, you'll be more motivated to do so. The best exercise is the exercise you'll do, etc. etc.

I think it's not so black and white. If I love Sphinx, which I do, I sure as hell am not going to force it on my users if I write e.g. a Rust crate-- I'd have to love rustdoc. Same with a TypeScript project, etc. Maybe there's a super convenient and cool and easy to use documentation builder, but if it doesn't warn or fail every time I cross-reference a nonexistent unit then I shouldn't be super enthused about it if I care about documentation reader, probably.

> You probably want to compare RST vs. Markdown

shrug You know what I mean

You seem really hung up on cross-references as links, but I'm not that big a fan. In particular, Sphinx docs will cross-reference themselves a lot, which is super confusing to me; it makes me think "wait is there a more canonical reference than what I'm reading?", then I click it, then I'm back at the top of the page/section I was just on.

Generally I prefer (fast, good) search, and Sphinx' isn't wonderful: it's basically `grep` for docs. I don't really need that, that's what `App site:textual.textualize.io` is for in DDG/Google.

> I sure as hell am not going to force it on my users if I write e.g. a Rust crate-- I'd have to love rustdoc

I mean, "have to love" is a contradiction. My point is that when you're a FOSS dev, you have to take any motivation you can get and avoid demotivations like the plague. Like in your case, I would assume you'd think twice about switching ecosystems from Python to Rust precisely because of your strong preference for Sphinx.

> shrug You know what I mean

Confusing file formats and documentation builders, but more importantly shrugging off miscommunication, makes me think you don't care much about documentation despite how much of it you wrote. Your position is thus unsurprising but also unlikely to inform my position (like I know it'd be pointless to argue about using static typing and running typecheckers with someone who sees ensuring code correctness as a chore).

> it makes me think "wait is there a more canonical reference than what I'm reading?"

Respect the user. If user lands on a doc section you don't know whether the user previously read everything else. You want to err on the side of more links, hitting a link and going back is quick but having to search is a major waste of time especially not knowing whether there is anything to be found in the first place. (This in particular applies to references, less so for tutorials that are intended to be read in order than jumped around.)

> I would assume you'd think twice about switching ecosystems from Python to Rust precisely because of your strong preference for Sphinx.

If I think Rust is the right tool and I want to work with Rust then I will use Rust. Documentation conventions are not much of a factor, they come with the territory, I don't see it as a demotivating chore or as a choice. Write language X? Use documentation system Y. Learn it and be satisfied with the end result.

If we are really talking about the least challenging ways to write docs then for me might be a Google Doc, should I do it? Of course I know it's bad, unsemantic, inconvenient to read and cross-link and generally completely wrong for the ecosystem so I can't possibly be motivated.

>> shrug You know what I mean

> Confusing file formats and documentation builders, but more importantly shrugging off miscommunication, makes me think you don't care much about documentation

Sorry what I meant here is what I wrote: you knew I meant ReST, and any further discussion was a waste of time. I think you're trying to weirdly score points here by pedantically insisting that there's a meaningful difference between Sphinx and ReST in the context of our conversation, but there isn't, and there's obviously no miscommunication.

I do care about documentation, but in a pragmatic sense. I've written a lot of it--primarily in Sphinx (I'm gonna keep doing this to you) and doxygen--but I've read a lot more, and as a result I'm pretty sensitive to the experience of users.

>> [Sphinx' relentless cross-referencing is confusing to me]

> Respect the user.

This is a good example. I brought up this issue I have with Sphinx as a user, and you dismissed my user experience by telling me to... respect myself? Maybe you think it's a good idea to err on the side of more links. Maybe I think it's a good idea to rely on high-level organizations and search. I don't know that there's an absolute good here. But it's worth saying that not even Wikipedia links everything it possibly can. That tracks with my experience where I find too many links to be noisy.

> Documentation conventions are not much of a factor, they come with the territory, I don't see it as a demotivating chore or as a choice. Write language X? Use documentation system Y. Learn it and be satisfied with the end result.

This seems contradictory with:

> If we are really talking about the least challenging ways to write docs then for me might be a Google Doc, should I do it? Of course I know it's bad, unsemantic, inconvenient to read and cross-link and generally completely wrong for the ecosystem so I can't possibly be motivated.

And this is exactly what I'm saying haha. I don't know why you're being so oppositional. You have strong opinions about documentation systems. If some ecosystem's default was "unsemantic, inconvenient to read and cross-link", you're saying you wouldn't be motivated. Great, then we agree! I think FOSS devs should be free to choose their own doc systems based on what motivates them too.

> 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.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.... 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.

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/

[1]: https://googleapis.dev/python/protobuf/latest/google/protobu...

> But again they don't export a Sphinx inventory so I cannot cross-reference their units

But they do! So you can!

The inventory is right here: https://textual.textualize.io/objects.inv. It's generated by mkdocstrings, the "autodoc" plugin for MkDocs. It's Sphinx compatible.

Reply on news.ycombinator.com