Doing the work

September was all about shipping the new system for Rubin Observatory user guides in Documenteer. When I first started working on documentation for Rubin back in 2015, I always struggled with getting Sphinx documentation themes to do exactly what we wanted. For years I told my colleagues we’d fix all the issues — from typography to navigation to branding and more… eventually. Now I think we’ve finally got to a point where we are shipping polished documentation sites we can really be proud of. And the best part is I didn’t have to do the ground-up production of a custom Sphinx theme. Instead, we used the new and awesome PyData Sphinx Theme as an open source foundation. I really appreciate how the PyData folks have thought through the customization and branding use cases. For example, CSS custom properties make it a snap to apply Rubin’s brand colours in both light and dark themes. In the past this would have been a fraught task that yielded rather fragile CSS overrides.

What I spend most of the month though was productizing the user guide theme and configuration for the Rubin organization. Sphinx documentation projects use a Python module, called conf.py for configuration. To help Rubin projects use the same core configuration (and therefore benefit from consistent features and branding), we provide a configuration module in Documenteer that each project can import into its conf.py file:

from documenteer.conf.guide import *

Each project still needs to customize its Sphinx configuration in many ways. The technically simple way to do this is to have each project extend the core configuration in its conf.py file. But in some cases this is tricky because you need to customize existing lists and dictionary provided by the core configuration. It’s just awkward and error prone.

What we’ve done instead is introduced a file, called documenteer.toml, where a user can configure their project. The documenteer.conf.guide configuration merges this information with the Sphinx conf.py file for you. This lets us also do smart and semi-automated configuration. For instance, if a project is a Python package, the configuration can automatically pull out the project’s name, version, and repository URL.

[project]
title = "Documenteer"
copyright = "2015-2022 Association of Universities for Research in Astronomy, Inc. (AURA)"

[project.python]
package = "documenteer"

Overall, the documenteer.toml file means we can document and support a well defined set of configuration that each Rubin documentation project can manipulate.

Within Rubin Observatory, this is the sort or work that I find both satisfying and also really powerful from an organizational perspective. We’re able to take together elements of the open source ecosystem, edit and mix them together, and then provide and document a simple interface that other members and teams in the observatory can use in their own work. Rather than personally running all the documentation sites for the entire observatory, I can help the entire observatory create their own documentation. That’s how a small team like ours can have an outsized influence on an organization.

Pursuits

Amanda and I joined our friend couple on a hike to McCrae Lake Conservation Reserve, a popular site just north of us that’s the beginning of the Canadian shield country. The purpose of the trip was to take some wedding anniversary shots for our friends, and they turned out adorably cute. I also flew the drone and managed to capture a glimpse of a beaver near it’s lodge. I put the video up on YouTube.

I’m getting the hang of Lumafusion and even had some fun mixing some nature sounds and atmospheric sound tracks from the Audiio library. Video editing gets easier the more you do it, and I could see this being something I want to keep doing more.

Down in the workshop I’ve been slowly getting the sliding trays for the tool chest project. I got the tray slides in (made from white oak) and milled the pine stock for the trays themselves.

Reading

Finished reading The Thursday Murder Club by Richard Osman, After Dark by Haruki Murakami, and Make Time by Jake Knapp and John Zeratsky. Make Time is a quick book with loads of strategies to experiment with for getting better at focusing. Amanda and I started reading Husband Material by Alexis Hall together, which is the sequel to Boyfriend Material.

Heavy rotation

Amanda and I went to see Carly Rae Jepson play in Ontario Park in Toronto for her So Good tour. And it was so good. Every song of hers is a hit and she sounded amazing with her band. Bleachers opened for her and it was really cool to see Jack Antonoff for the first time.

On screen

We’ve been watching Only Murders in the Building, a hilarious take on the true crime podcast phenomenon with Steve Martin, Martin Short, and Selena Gomez. Enough said!