4 ms·

> Using a general-purpose static site generator for Python docs feels just wrong There's a spectrum on this; a lot of stuff in the async ecosystem uses mkdocs

> Using a general-purpose static site generator for Python docs feels just wrong There's a spectrum on this; a lot of stuff in the async ecosystem uses mkdocs (FastAPI, etc.) for example. I'd also argue that Markdown is known by waaaaay more SWEs than Sphinx--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. That says a lot. 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. My day job's in Python, and I spend a lot of time reading through various Sphinx documentation. Sure it's possible to make a great Sphinx site, but most people just add bare minimum docstrings and leave you to figure out the rest. Like you say, people generate docs, and I don't think Sphinx has extra magic that "makes you" generate better ones. 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. [0]: https://textual.textualize.io/reference/app/ https://textual.textualize.io/reference/app/

throwaway290 4y ago
> 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.
- camgunz 4y ago
  > 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.
  - throwaway290 4y ago
    > 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.

throwaway290 4y ago

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

camgunz 4y ago
> 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.
- throwaway290 4y ago
  > 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.