Hacker News Reader

> Another profoundly important consequence of this architecture: all internal links are guaranteed to always resolve (you get warnings/errors if you link somewhere that doesn't exist). I previously wrote about how baffling it is that this is not the industry standard for docs sites: https://technicalwriting.dev/src/link-text-automation.html

This, so much this.

It's a problem in an even more general form (for you're writing about linking to sections within a page): the number of CMS systems or static site builders that make you insert the final URL when you write is _insane_.

If the slug changes, you reorganise your site - now you have to do a search and replace through the site to update all your links.

Static site generators could enable linking like [Hello](../hello.md) and resolve the link at build time, instead of expecting everyone to type [Hello](/why/hello/). And yet the popular ones I've used or looked at don't do this.

It seems to be a marmite feature (you love it or you don't): I've raised it with static site builder team members and received a "Why would you want that?" response. Explanations got nowhere. I'm not sure if it's a niche feature, you have to have experienced the problem to appreciate the solution, or people are used to writing once and not maintaining for a decade or longer, but it'd be great to see wider support.

Agreed that Sphinx is extraordinary and wildly underrated. Sphinx is the only architecturally sound, extensible, widely used documentation framework that I know of. Its plugin ecosystem is amazing and gives me incredible leverage to improve documentation for teams and projects.

I'm not a fan of reStructuredText, but nowadays it's possible to do most things that previously tightly coupled Sphinx to RST in Markdown, courtesy of MyST-Parser: https://github.com/executablebooks/MyST-Parser

Except that the plugins are not compatible with each other or the latest version. That means I'm seeing some bugs that are fixed in the latest but I can't get the fix because my doxygen plugin doesn't work with the latest, and even if it did is the mermaid plugin updated yet? (please don't ask which versions of each I'm using - I believe there are at least 2 different ones that can do both of the above and they all have different abilities...)

Yes, what this means in practice is that it's easy to customize common aspects of your site (such as how images are displayed).

I found this to be very easy using Markdown+pandoc. I turned image tags containing youtube links to thumbnails with video tag and alt text, hooked up image tags to local video files to ffmpeg to optimize and resize videos to then do the same, etc in a few lines of code.

I did not know about Sphinx until your comment (I'll get to my 2-day delay in response, briefly). I've been doing technical writing "on the side" as my dev work allows, for 20+ years. I've been a TeX/custom-XSL sort of dude the whole time.

I just ported a 200+ page book documenting an internal language/VM/abstraction-layer to Sphinx ... holy moly, this is a life changing system!

I wish the documentation for Sphinx, itself, had a lower ramp and/or more examples; otherwise, I'm still in a pretty fantastic honeymoon phase.

My two main lines of research are how to build good looking PDF (books); and, some sort of system to let me cut a book into POSIX compliant man pages by chapter/section.

If you want Sphinx to achieve that breakout success, priority #1 should be to get high-quality, beautiful themes.

At least for me, aesthetics are a high-priority factor when deciding which site generator to use. Hugo and Gatsby have great built-in themes, and I have chosen them for projects before based largely on this fact.

The Sphinx themes here [0] and here [1] are various levels of "meh" to bland.

Look at the standard Sphinx RTD theme: https://sphinx-rtd-theme.readthedocs.io/en/stable/

Now, compare it to documentation sites like:

- Apple's: https://developer.apple.com/documentation/swift/array

- Fluent UI: https://react.fluentui.dev/?path=/docs/concepts-developer-po...

RTD looks dated in comparison.

[0]: https://sphinx-themes.org/

[1]: https://sphinxthemes.com/#featured-themes

Looking at Fluent UI VS featured-themes, I don't see a difference.

I'll ignore Apple because: 1) It loads _extremely_ slowly (10+ seconds). 2) Just looks like a dark theme and nothing more.

Apple's site loads for me in under 1 second with a clean cache force-reload.

The featured themes, in general, have poor typography and whitespace, poor formatting and alignment, and uninspired colors and design. Furo [0] is the best-designed of them and would make a solid foundation for a proper theme.

[0]: https://sphinxthemes.com/themes/furo

I don't disagree that themes are an important part of marketing a tool. The engineer in me doesn't want that to be the case, but I recognise that people like pretty things, it makes a difference.

However I'd push back a little. That Fluent UI doc site looks like every other doc site from an open source project started since ~2020 that I've seen, and this means that I have certain expectations: I expect the project to be immature, I expect the docs to be incomplete or out of date, I expect the search to be an annoying AI search that does a worse job than the basic full text search that I expect elsewhere, I expect that to get anything of substance done I'm going to have to hang out on a Discord server. When I see a ReadTheDocs site though with that default theme, I expect the project to be somewhat mature, I expect it to basically work. I expect the docs to be fairly complete.

Are these expectations fair? Not really, but that's the whole point here. Open Source projects are not immune from marketing, and when marketing, what other similar projects do will affect how people respond to your marketing. Nothing exists in isolation.

In my experience, engineers think marketing doesn't apply to them, but these impressions really do matter.

I agree that more stellar, super-visually-appealing themes will help Sphinx get to the next level.

One nit: I called Sphinx a sleeping giant because it's already majorly successful in the Python ecosystem. Pretty much all big Python docs sites are built on top of Sphinx, including docs.python.org. But I think it's fair to say that when Sphinx starts getting major adoption outside of the Python ecosystem then we can start calling it a breakout success.

Some drive-by feedback on pigweed.dev: It seems like it’s missing a “What is Pigweed” section? I was wondering what Pigweed does and eventually found the Github README, which is somewhat better. (I’ve used Arduino, but I’m not quite sure what I’m looking at.)

Thanks. It's basically middleware for large, professional embedded development teams creating mass market products, usually consumer electronics. The four pillars in the "What is Pigweed?" section on the homepage [1] really do sum up a lot of what we do, but the reality is that it's a difficult "product" to explain in general. But rest assured that it's definitely on my radar that there is huge room for improvement in our "What is Pigweed?" content.

[1] https://pigweed.dev/#what-is-pigweed

Apparently I'm bad at skimming. I did see that section, though apparently not the heading :)

The first part didn't really do it for me because it seemed too meta:

"Over 150 libraries" - to do what? (Actually, some good examples are in the next section.) "Automation" - to build, test, and lint what? "Environments" - to make builds reproducible, to do what? "Frameworks" - turnkey solutions for what?

They are clickable, though, so maybe I should have clicked. :)

> We provide libraries (modules) for strings, time, assertions, logging, serial communication, remote procedure calls (RPC), and much more.

Maybe put that up front?

Looks like "frameworks" are still work in progress; maybe I'll check back someday when they get to Raspberry Pi Pico support.

I liked it as well. But many years ago I tried to get them to implement parts of a book, and they never did. You can work around somewhat by hardcoding chapter numbers—but I don’t feel sphinx is suitable for book-length docs without that simple feature.

Until you need to make a physical book with Sphinx or write custom tooling with it...

Why do you like Sphinx so much? Have you ever used MkDocs/Material for MkDocs? How do they compare?

At my last job I spent a fair amount of time on documentation, but I don't have a great understanding of what technical writers like/dislike, or what documentation systems are best.

I like sphinx because I can make it do all the weird links between documents that I want. Markdown can't do that. I've never used MkDocs so I cannot comment.

I've used both extensively. (Material for) MkDocs is easy to set up and gives very good UX for users. Sphinx is hard to set up and provides better UX in some ways (internal links are on another level entirely), and worse UX in others (the themes are all worse than Material for MkDocs, every single one).

Ok, what about DITA?

Also very powerful. Haven't worked with it in years; need to revisit.

> reStructuredText (reST) by itself can be pretty rough. reST combined with Sphinx is pretty great.

So, you've made a convincing argument of why we should prefer Markdown to reST, 9 times out of 10. If we're working with Sphinx we'll give it serious consideration.

I'm not really sure what your point is. What you're saying agrees with both the parent and the OP.

My point is that the reason GP prefers rST is a reason not to prefer it, usually.

I heard recently that MyST [1] now has full feature parity with everything that reST provides. If I were starting a new project today I would seriously look into Markdown-based Sphinx site powered through MyST. For Pigweed we collectively don't seem to hate reST enough to justify the huge project of migrating everything over from reST to Markdown.

So yeah, I don't really have strong opinions on sticking with rest per so. I only have strong opinions about Sphinx being probably the best choice out there for large docs sites.

[1] https://myst-parser.readthedocs.io/en/latest/