New theme for Rubin's Sphinx documentation

Data Management
#1

The past few weeks we’ve been working on the next generation of theming for Rubin’s user documentation. Although the work isn’t done yet, we wanted to make sure everyone’s in the loop and that you have a chance to provide feedback.

The documentation for the new theme (which is also using the new theme!) is at User guides — Documenteer

CleanShot 2022-09-20 at 16.16.32
CleanShot 2022-09-20 at 16.16.321342×1312 157 KB
CleanShot 2022-09-20 at 16.17.16
CleanShot 2022-09-20 at 16.17.161339×1310 158 KB

Features

Some of the key features:

Where this theme will be used, and where it won’t be used yet

This Sphinx configuration can be used for nearly (*) all of Rubin’s user documentation sites. So everything from Data Release/Data Preview and Rubin Science Platform documentation sites, to our beloved Developer Guide, to all the user guides we create for specific services and software projects.

This theme won’t be used for technical notes, although that’s coming soon after too. The technical note theme/configuration will work and look a lot like our user documentation theme, but it’ll be tailored to the specific needs and format of technotes.

On day 1 this theme won’t be used for the LSST Science Pipelines, though that’ll very much be the second phase of the rollout. The LSST Science Pipelines have some specific build and configuration needs. But the Pipeline’s documentation will look just like our other user guides.

Roll out

In the next week or two, I’ll put the finishing details on the first release of the theme configuration, and incorporate your feedback as well. We’ll also start slowly rolling the theme out to various SQuaRE projects.

Once we make a full Documenteer release with the new theme release, it’ll be time to roll out the theme to the rest of our documentation projects. I’m hoping that each team will be able to upgrade their own projects, though I’ll be available for help in pull requests and in dm-docs-support on Slack. Frossie has also suggested we could arrange a Zoom session where you could work on updating your project to the new theme and you can get advice in real-time.

I’ll add that adopting the theme and configuration is quite easy — we’ve worked hard on the configuration experience. What might be challenging, but also quite fruitful, for many projects is arranging your documentation’s toctrees to make the best use of the theme’s navigational structure. I’ve written a documentation page on tips for doing this.

Let me know in the comments if a Zoom session would be useful and I can organize it. Lastly, you can try out the theme now (caveat emptor) by installing a beta release of documenteer[guide] 0.7 from PyPI and following the docs.

Let me know what you think, what questions you have, and what features you’d like to see added in the comments below. Thanks!

1 Like
#2

I have to say that I find the new theme very disorienting. It looks like there are three different navigational menus in different directions, so I’m never sure what I’m supposed to be looking at. It doesn’t help that in the two examples I looked at (User guides — Documenteer and Pipelines — Documenteer) both the left and right sidebars have similar-looking headings. Would it be possible to (for example) only display the page navigation, without the list of all other topics?

I’m also worried about the content organization guide (in my case, the application of interest is package docs). Aside from the question of separating content and presentation, it looks like the two highest-level headings for a particular page are now to be defined in index.rst? Does this mean that each page – formerly a largely self-contained unit – must now be designed to fit into one and only one place in a linear sequence?

1 Like
#3

I realise it takes a moment to re-orient after moving from the old theme, but the “major site areas at the top bar, page navigation at the left bar” is actually a very common cotemporary pattern for technical documentation, eg:
https://numpy.org/doc/stable/reference/index.html

Everything is of course configurable, but one of the reasons of getting this out on our (SQuaRE) sites first is to let people get used to it and then we will of course be reaching out to pipelines.lsst.io stakeholders to discuss how best to configure site navigation for the consumers of those docs.

#4

@kfindeisen Just narrow your window, and the disorienting right-hand in-page navigation bar will go away :slight_smile: . And if you narrow even more, the top and left bars go away too (replaced by a single hamburger menu). But the fourth navigation item (previous/next at the bottom of the scrolling part of the page) is still there.

If you shorten the window beyond the length of the left bar, the current topic is not forced to be visible, which can be slightly strange for topics at the end of the list.

I’ve seen other themes try to embed the in-page navigation in the left bar, but that often has even more issues with length/scrolling.

#5

Thanks for the feedback @kfindeisen ! The two examples you mentioned happen to be the landing pages for individual sections and the main role of those index.rst pages is to have toctree directives listing their contents. That’s why you’re seeing all this duplication between the left-most column (section nav) and the centre column (content), and that the right most column (in-page headers) is blank.

But I’m glad you brought this up because maybe it’d be better to have “hidden” toctrees on these landing pages to leave the section navigation to the left side bar. That would leave the index.rst content open to other roles, like providing more overview-type content. I’ll experiment on this and see if we can come up with a pattern.

I’ll also mention that the sidebars (both left and right) can be removed on a page-by-page basis). For example, in the Change log it didn’t make sense to have section navigation because the “section” is only one page. Change Log — Documenteer

The answer is somewhere in between. The theme we’re currently using for pipelines.lsst.io basically lacks a global-level navigation in the theme’s infrastructure, and relies entirely on toctrees within pages to create navigation. The new theme uses these toctrees to show the global navigation. So ultimately the site navigation has been, and continues to be a hierarchy with linear sequences of pages at each level; but I think we’ll find this doesn’t materially conflict with writing self-contained pages and using hyperlinks within pages to help users find information. The toctrees are just another (and infrastructurally necessary) organizational axis. Regardless, as Frossie says, we’ll work closely with your and the rest of the Pipelines team to roll this out to pipelines.lsst.io.

#6

Sorry, that was a miscommunication on my part. I meant those branches of the site, not the landing pages themselves. Would Organizing content in a Rubin user guide — Documenteer (the specific page) be a better example of what I meant by “similar-looking headings to the left and right”?