Selective prose linting with Vale’s glob switch

Vale is an open source CLI tool for linting prose (if you’re not linting prose yet, why not? I never want to go back). I typically use it for everything, locally and in CI, and it’s especially valuable now I’m working for a company that uses US English. You’d think that most of the challenges would be caused by the majority of non-native English language contributors? Nope, most of the chaos comes from the token Brit :)

I ran into one challenge though where I didn’t want to enable Vale for everything: a large internal documentation repo. This is the catch-all of things we should share with one another and like most internal company documentation sites, there is a lot going on. I assembled a very minimal set of Vale rules and still the first pass netted me over 10k errors. Luckily, Vale has a --glob option, but it took me a while to find how to exclude multiple files and directories using it, so here’s the example for future-me, and anyone else who needs to see it! Continue reading

Sphinx extensions for developer portals

I’ve been gushing about docs-as-code, but realised that I haven’t shared many hands-on tips for actually building different types of sites in this sort of toolchain. I’ve been mostly using Sphinx which generates much better-looking documentation than its website suggests. It’s a python-based static site generator, with a thriving community and lots of great extensions. Today I thought I’d share the extensions I use the most for developer portals (like the Aiven docs, one of my work projects and the source of the screenshots in this post) and what I like about them. Spoiler: may contain a theme as well as the extensions.