4 ms·

I don't think the word "pythonic" is applicable outside of code. I used Sphinx for years, but mkdocs produces far better docs. Especially when combined with mk

by willm 4y ago

I don't think the word "pythonic" is applicable outside of code. I used Sphinx for years, but mkdocs produces far better docs. Especially when combined with mkdocs-material.

throwaway290 4y ago
> I don't think the word "pythonic" is applicable outside of code. I view it quite differently. Like TSDoc for TypeScript or Ruby-Doc for Ruby, there's Sphinx for Python. Using a general-purpose static site generator for Python docs feels just wrong, like you wouldn't use Wix instead of rustdoc for a Rust crate... But maybe that's just me. > I used Sphinx for years, but mkdocs produces far better docs. Especially when combined with mkdocs-material. IMO humans write the docs, not Sphinx or mkdocs, and human approach is what ultimately determines whether the docs are good. From this perspective Textual can absolutely have good docs, and especially since they mentioned Django as the inspiration I'm reasonably sure they will. However, the use of documentation builder can affect how easy it is to achieve certain niceties: Sphinx with autodoc, for example, offers direct links from docs to implementation and cross-package document linking. The builder can introduce useful syntax sugar and salt: Sphinx+RST, for example, subtly encourages proper "rich" linking to actual Python units rather than using dumb identifiers everywhere (see single backtick behavior in RST vs. Markdown), which in turn forces you to write better docs (you must document units you want to cross-reference or you'll see warnings during doc generation) and think about structuring API in a way that makes it easier to document and maintain that documentation. (On that note, I haven't seen a project anything that paralleled Django documentation by all metrics, and that one is built using Sphinx.) So while the docs can be great regardless the choice of a build system in case of Textual IMO still breaks the familiarity pattern for Python documentation readers and contributors, breaks interoperability within Python ecosystem (no links to source or to/from third-party packages), and goes with a more limited markup language than RST for no obvious (to me) reason.
- camgunz 4y ago
  > 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.

by willm 4y ago

I don't think the word "pythonic" is applicable outside of code. I used Sphinx for years, but mkdocs produces far better docs. Especially when combined with mkdocs-material.

throwaway290 4y ago

> I don't think the word "pythonic" is applicable outside of code. I view it quite differently. Like TSDoc for TypeScript or Ruby-Doc for Ruby, there's Sphinx for Python. Using a general-purpose static site generator for Python docs feels just wrong, like you wouldn't use Wix instead of rustdoc for a Rust crate... But maybe that's just me. > I used Sphinx for years, but mkdocs produces far better docs. Especially when combined with mkdocs-material. IMO humans write the docs, not Sphinx or mkdocs, and human approach is what ultimately determines whether the docs are good. From this perspective Textual can absolutely have good docs, and especially since they mentioned Django as the inspiration I'm reasonably sure they will. However, the use of documentation builder can affect how easy it is to achieve certain niceties: Sphinx with autodoc, for example, offers direct links from docs to implementation and cross-package document linking. The builder can introduce useful syntax sugar and salt: Sphinx+RST, for example, subtly encourages proper "rich" linking to actual Python units rather than using dumb identifiers everywhere (see single backtick behavior in RST vs. Markdown), which in turn forces you to write better docs (you must document units you want to cross-reference or you'll see warnings during doc generation) and think about structuring API in a way that makes it easier to document and maintain that documentation. (On that note, I haven't seen a project anything that paralleled Django documentation by all metrics, and that one is built using Sphinx.) So while the docs can be great regardless the choice of a build system in case of Textual IMO still breaks the familiarity pattern for Python documentation readers and contributors, breaks interoperability within Python ecosystem (no links to source or to/from third-party packages), and goes with a more limited markup language than RST for no obvious (to me) reason.

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