Screwtape

Screwtape at

I'm writing some documentation, and it started out as a simple README.md as you'd expect... but it's grown and trying to maintain documentation in a single .md is difficult, especially when you need to start making assumptions about how the resulting markdown renderer will auto-linkify headings and such.

I said "I know, I'll switch to a Real Documentation System, like Sphinx!" And sure enough, splitting documentation across multiple files and getting a table-of-contents and an index all for free is pretty sweet... but Sphinx doesn't make headings into link-targets at all. Which means for all the dozens of times I link between docs, I need to manually put an ID marker in front of every section header.

That doesn't sound fun at *all*. :(

clacke@libranet.de ❌ likes this.