The next generation of Rubin Observatory technotes with Documenteer 1.0

Data Management DM Notifications
#1

Technotes are a way for the Rubin Observatory team to communicate with web-based documentation that’s written the same way you code. Together, we’ve written hundreds of technotes that document the construction of Rubin Observatory. When we launched technotes in 2015, though, we’d cobbled together a Sphinx-based system that worked but wasn’t great in fit and finish. We always knew we’d have to go back and build on a better foundation. Today, with the release of Documenteer 1.0, we have that foundation.

The new technotes feature a responsive design that’s as readable on a phone as your desktop, in a dark room or out on a bright sunny day. With Rubin’s imagotype, colors, and typeface, your technotes fit into the observatory’s visual identity.

For authors, you can now write your technotes equivalently in Markdown or reStructuredText (LaTeX/PDF-based documents are unaffected by the new release since they use a separate framework).

Learn more about Rubin technotes in the Documenteer documentation.

technote-screenshots
technote-screenshots1920×1233 403 KB

Transitioning to the new format

Starting today, reStructuredText and Markdown technotes created with @sqrbot-jr create project use the new technote format.

We’ve created a tool to help you migrate your existing technotes to the new format. Read our migration guide.

If you’re in the middle of a technote project right now, you might not want to migrate right away. That’s ok. You can continue to use the older version of Documenteer by modifying your requirements.txt file to use the pre-1.0 release of Documenteer:

documenteer[technote]<1.0

You’ll want to migrate sooner than later to take advantage of the new features.

More features

  • The project template uses tox to build your technote in an isolated Python environment. This keeps your technotes separate from other Python projects and independent from rubin-env and other types of multipurpose conda environments. Nothing changes from your perspective; continue to run make html to compile a technote. All you need to do now is run make init to make sure tox is installed first.

  • The title and abstract for your technote are now part of the document’s content, not a separate metadata file. The top-level heading is the technote’s title, and the new abstract directive is where you’ll write your summary.

  • Other metadata for technotes, along with Sphinx build configuration, is now contained in a technote.toml file. This TOML file replaces the metadata.yaml file you might be familiar with. Here’s the full schema for technote.toml.

  • The new metadata system for technotes is designed to be compatible with standard metadata schemas. This will allow us to list technotes on popular bibliographic services. Metadata about authors is now derived from authordb.yaml in lsst/lsst-texmf so that authors are consistently identified across projects. New commands let you add authors based on author ID and sync author information from lsst/lsst-texmf. See the author metadata docs for details.

  • Technotes have a natural lifecycle. They start out as incomplete drafts, mature into stable documents, and might eventually become deprecated. New metadata allows you to indicate this status. For deprecated technotes, you can even include links to superseding documents.

  • Your technote can include a references section link to traditional literature. Now the bibliography directive in technotes automatically load BibTeX files from lsst/lsst-texmf. Individual technote repositories no longer vendor a copy of these bib files.

  • We’ve had fun creating diagrams from code for our user guides. Now Mermaid diagrams are available in technotes. This will help you create diagrams that anyone can maintain without proprietary design software. Of course, you can continue to include images as well.

Future directions

The new technote platform allows us to implement exciting features like executable technotes with Jupyter notebook, PDF exports for technotes, and inclusion of citation directions on technotes.

Rubin’s new technotes are built on top of a new package we created called Technote. This package provides the base theme and metadata system that organizations can build on to create their own technotes.

4 Likes