Update to TOM documentation theme by rachel3834 · Pull Request #1476 · TOMToolkit/tom_base

rachel3834 · 2026-03-25T23:45:21Z

I felt it was time to update the theme used for the Toolkit's documentation on ReadTheDocs.

This PR implements just the new theme and the necessary dependencies. I'm considering it preliminary because I'd like to do some reorganization of the menu structure to make it more navigable within this theme, but I thought that would be too much for a single PR. So I'm submitting this now to get some feedback

…encies

jchate6

This looks great!

However, I'm not a huge fan of the navigation in this format.
A horizontal nav bar doesn't lend itself well to our current list of categories.
I think if we adopt this we will want to change our tree substantially.

rachel3834 · 2026-04-09T16:13:10Z

Thanks for your feedback @jchate6 !
Yes, I agree the navigation needs a revamp. I just wanted to get your input on the underlying theme changes before I go ahead with that. But I think this is a good chance to update the navigation in general, so that'll be my next step.

rachel3834 · 2026-05-08T18:33:37Z

I've gone through all the documentation, added more explanatory text and restructured the menus and navigation to be (hopefully) more intuitive for users.

jchate6

I wouldn't worry too much about the dataservices/broker stuff. That will all be handled in #1559 .

I'm going through the specifics, but I'm worried we are loosing a lot by removing our tree. I think it's a less than ideal user experience to have to search through text for a reasonable link to our pages rather than having them all listed in a more organized way.

We should talk about if there is a way to maintain the tree while also not having it take up as much space. I think my preference would be to have the tree in a side bar like we have for the API docs if possible.

Thoughts?

jchate6

I've merged the conflicts with the Broker removal branch.
Take a look at the dataservices page now for an example of how the trees behave on the left bar.
I didn't remove them for that page.

Also, there are MANY issues when building the docs.
A large number of these come from not having most pages on any tree basically making them unsearchable.
Some of them are formatting issues, some of them are reference issues.
You can check these errors when building the docs locally.
Let me know if you'd like me to take care of these.

/home/jchatelain/git/tom_base/tom_dataservices/dataservices.py:docstring of tom_dataservices.dataservices.MissingDataException:1: WARNING: duplicate object description of tom_dataservices.dataservices.MissingDataException, other instance in api/tom_dataservices/exceptions, use :no-index: for one of them
/home/jchatelain/git/tom_base/tom_dataservices/dataservices.py:docstring of tom_dataservices.dataservices.NotConfiguredError:1: WARNING: duplicate object description of tom_dataservices.dataservices.NotConfiguredError, other instance in api/tom_dataservices/exceptions, use :no-index: for one of them
/home/jchatelain/git/tom_base/tom_dataservices/dataservices.py:docstring of tom_dataservices.dataservices.MissingDataException:1: WARNING: duplicate object description of tom_dataservices.dataservices.MissingDataException, other instance in api/tom_dataservices/data_services, use :no-index: for one of them
/home/jchatelain/git/tom_base/tom_dataservices/dataservices.py:docstring of tom_dataservices.dataservices.NotConfiguredError:1: WARNING: duplicate object description of tom_dataservices.dataservices.NotConfiguredError, other instance in api/tom_dataservices/data_services, use :no-index: for one of them
/home/jchatelain/git/tom_base/tom_dataservices/models.py:docstring of tom_dataservices.models.DataServiceQuery:3: ERROR: Unexpected indentation. [docutils]
/home/jchatelain/git/tom_base/tom_dataservices/models.py:docstring of tom_dataservices.models.DataServiceQuery:5: ERROR: Unexpected indentation. [docutils]
/home/jchatelain/git/tom_base/tom_dataservices/models.py:docstring of tom_dataservices.models.DataServiceQuery:6: WARNING: Block quote ends without a blank line; unexpected unindent. [docutils]
/home/jchatelain/git/tom_base/tom_observations/facilities/lco.py:docstring of tom_observations.facilities.lco.LCOSettings.get_sites:5: ERROR: Unexpected indentation. [docutils]
/home/jchatelain/git/tom_base/tom_observations/facilities/lco.py:docstring of tom_observations.facilities.lco.LCOSettings.get_sites:10: WARNING: Definition list ends without a blank line; unexpected unindent. [docutils]
/home/jchatelain/git/tom_base/tom_observations/facilities/lco.py:docstring of tom_observations.facilities.lco.LCOSettings.get_sites:11: WARNING: Block quote ends without a blank line; unexpected unindent. [docutils]
/home/jchatelain/git/tom_base/tom_observations/facilities/lco.py:docstring of tom_observations.facilities.lco.LCOSettings.get_weather_urls:4: ERROR: Unexpected indentation. [docutils]
/home/jchatelain/git/tom_base/tom_observations/facilities/lco.py:docstring of tom_observations.facilities.lco.LCOSettings.get_weather_urls:6: ERROR: Unexpected indentation. [docutils]
/home/jchatelain/git/tom_base/tom_observations/facilities/lco.py:docstring of tom_observations.facilities.lco.LCOSettings.get_weather_urls:9: WARNING: Definition list ends without a blank line; unexpected unindent. [docutils]
/home/jchatelain/git/tom_base/tom_observations/facilities/lco.py:docstring of tom_observations.facilities.lco.LCOSettings.get_weather_urls:10: WARNING: Block quote ends without a blank line; unexpected unindent. [docutils]
/home/jchatelain/git/tom_base/tom_observations/facilities/lco.py:docstring of tom_observations.facilities.lco.LCOSettings.get_weather_urls:11: WARNING: Block quote ends without a blank line; unexpected unindent. [docutils]
/home/jchatelain/git/tom_base/tom_observations/facilities/soar.py:docstring of tom_observations.facilities.soar.SOARSettings.get_sites:5: ERROR: Unexpected indentation. [docutils]
/home/jchatelain/git/tom_base/tom_observations/facilities/soar.py:docstring of tom_observations.facilities.soar.SOARSettings.get_sites:10: WARNING: Definition list ends without a blank line; unexpected unindent. [docutils]
/home/jchatelain/git/tom_base/tom_observations/facilities/soar.py:docstring of tom_observations.facilities.soar.SOARSettings.get_sites:11: WARNING: Block quote ends without a blank line; unexpected unindent. [docutils]
/home/jchatelain/git/tom_base/tom_observations/facilities/soar.py:docstring of tom_observations.facilities.soar.SOARSettings.get_weather_urls:4: ERROR: Unexpected indentation. [docutils]
/home/jchatelain/git/tom_base/tom_observations/facilities/soar.py:docstring of tom_observations.facilities.soar.SOARSettings.get_weather_urls:6: ERROR: Unexpected indentation. [docutils]
/home/jchatelain/git/tom_base/tom_observations/facilities/soar.py:docstring of tom_observations.facilities.soar.SOARSettings.get_weather_urls:9: WARNING: Definition list ends without a blank line; unexpected unindent. [docutils]
/home/jchatelain/git/tom_base/tom_observations/facilities/soar.py:docstring of tom_observations.facilities.soar.SOARSettings.get_weather_urls:10: WARNING: Block quote ends without a blank line; unexpected unindent. [docutils]
/home/jchatelain/git/tom_base/tom_observations/facilities/soar.py:docstring of tom_observations.facilities.soar.SOARSettings.get_weather_urls:11: WARNING: Block quote ends without a blank line; unexpected unindent. [docutils]
/home/jchatelain/git/tom_base/tom_observations/facilities/blanco.py:docstring of tom_observations.facilities.blanco.BLANCOSettings.get_sites:5: ERROR: Unexpected indentation. [docutils]
/home/jchatelain/git/tom_base/tom_observations/facilities/blanco.py:docstring of tom_observations.facilities.blanco.BLANCOSettings.get_sites:10: WARNING: Definition list ends without a blank line; unexpected unindent. [docutils]
/home/jchatelain/git/tom_base/tom_observations/facilities/blanco.py:docstring of tom_observations.facilities.blanco.BLANCOSettings.get_sites:11: WARNING: Block quote ends without a blank line; unexpected unindent. [docutils]
/home/jchatelain/git/tom_base/tom_observations/facilities/blanco.py:docstring of tom_observations.facilities.blanco.BLANCOSettings.get_weather_urls:4: ERROR: Unexpected indentation. [docutils]
/home/jchatelain/git/tom_base/tom_observations/facilities/blanco.py:docstring of tom_observations.facilities.blanco.BLANCOSettings.get_weather_urls:6: ERROR: Unexpected indentation. [docutils]
/home/jchatelain/git/tom_base/tom_observations/facilities/blanco.py:docstring of tom_observations.facilities.blanco.BLANCOSettings.get_weather_urls:9: WARNING: Definition list ends without a blank line; unexpected unindent. [docutils]
/home/jchatelain/git/tom_base/tom_observations/facilities/blanco.py:docstring of tom_observations.facilities.blanco.BLANCOSettings.get_weather_urls:10: WARNING: Block quote ends without a blank line; unexpected unindent. [docutils]
/home/jchatelain/git/tom_base/tom_observations/facilities/blanco.py:docstring of tom_observations.facilities.blanco.BLANCOSettings.get_weather_urls:11: WARNING: Block quote ends without a blank line; unexpected unindent. [docutils]
/home/jchatelain/git/tom_base/tom_observations/utils.py:docstring of tom_observations.utils.get_sidereal_visibility:25: WARNING: Definition list ends without a blank line; unexpected unindent. [docutils]
/home/jchatelain/git/tom_base/docs/api/tom_targets/models.rst:4: ERROR: Unknown directive type "autosummary".

.. autosummary:: [docutils]
WARNING: missing attribute mentioned in :members: option: module tom_targets.templatetags.targets_extras, attribute aladin [autodoc]
/home/jchatelain/git/tom_base/docs/code/plugins.rst:2: WARNING: Duplicate explicit target name: "github link". [docutils]
/home/jchatelain/git/tom_base/docs/code/plugins.rst:2: WARNING: Duplicate explicit target name: "github link". [docutils]
/home/jchatelain/git/tom_base/docs/code/plugins.rst:2: WARNING: Duplicate explicit target name: "github link". [docutils]
/home/jchatelain/git/tom_base/docs/code/plugins.rst:2: WARNING: Duplicate explicit target name: "github link". [docutils]
/home/jchatelain/git/tom_base/docs/code/plugins.rst:2: WARNING: Duplicate explicit target name: "github link". [docutils]
/home/jchatelain/git/tom_base/docs/code/plugins.rst:2: WARNING: Duplicate explicit target name: "github link". [docutils]
/home/jchatelain/git/tom_base/docs/code/plugins.rst:2: WARNING: Duplicate explicit target name: "github link". [docutils]
/home/jchatelain/git/tom_base/docs/code/plugins.rst:2: WARNING: Duplicate explicit target name: "github link". [docutils]
/home/jchatelain/git/tom_base/docs/code/plugins.rst:2: WARNING: Duplicate explicit target name: "github link". [docutils]
/home/jchatelain/git/tom_base/docs/code/plugins.rst:2: WARNING: Duplicate explicit target name: "github link". [docutils]
/home/jchatelain/git/tom_base/docs/code/plugins.rst:2: WARNING: Duplicate explicit target name: "github link". [docutils]
/home/jchatelain/git/tom_base/docs/code/plugins.rst:113: WARNING: Definition list ends without a blank line; unexpected unindent. [docutils]
/home/jchatelain/git/tom_base/docs/code/plugins.rst:2: WARNING: Duplicate explicit target name: "github link". [docutils]
/home/jchatelain/git/tom_base/docs/code/plugins.rst:2: WARNING: Duplicate explicit target name: "github link". [docutils]
/home/jchatelain/git/tom_base/docs/code/plugins.rst:2: WARNING: Duplicate explicit target name: "github link". [docutils]
/home/jchatelain/git/tom_base/docs/code/plugins.rst:2: WARNING: Duplicate explicit target name: "github link". [docutils]
/home/jchatelain/git/tom_base/docs/code/plugins.rst:2: WARNING: Duplicate explicit target name: "github link". [docutils]
/home/jchatelain/git/tom_base/docs/code/plugins.rst:2: WARNING: Duplicate explicit target name: "github link". [docutils]
/home/jchatelain/git/tom_base/docs/code/plugins.rst:2: WARNING: Duplicate explicit target name: "github link". [docutils]
/home/jchatelain/git/tom_base/docs/code/plugins.rst:2: WARNING: Duplicate explicit target name: "github link". [docutils]
/home/jchatelain/git/tom_base/docs/code/plugins.rst:2: WARNING: Duplicate explicit target name: "github link". [docutils]
/home/jchatelain/git/tom_base/docs/code/plugins.rst:2: WARNING: Duplicate explicit target name: "github link". [docutils]
/home/jchatelain/git/tom_base/docs/code/plugins.rst:2: WARNING: Duplicate explicit target name: "github link". [docutils]
/home/jchatelain/git/tom_base/docs/code/plugins.rst:2: WARNING: Duplicate explicit target name: "github link". [docutils]
/home/jchatelain/git/tom_base/docs/code/plugins.rst:2: WARNING: Duplicate explicit target name: "github link". [docutils]
/home/jchatelain/git/tom_base/docs/introduction/about.rst:66: WARNING: Inline interpreted text or phrase reference start-string without end-string. [docutils]
/home/jchatelain/git/tom_base/docs/targets/index.rst:4: WARNING: Inline literal start-string without end-string. [docutils]

checking consistency... /home/jchatelain/git/tom_base/docs/api/affiliated.rst: WARNING: document isn't included in any toctree
/home/jchatelain/git/tom_base/docs/api/modules.rst: WARNING: document isn't included in any toctree
/home/jchatelain/git/tom_base/docs/code/automation.rst: WARNING: document isn't included in any toctree
/home/jchatelain/git/tom_base/docs/code/backgroundtasks.rst: WARNING: document isn't included in any toctree
/home/jchatelain/git/tom_base/docs/code/custom_code.rst: WARNING: document isn't included in any toctree
/home/jchatelain/git/tom_base/docs/code/querying.rst: WARNING: document isn't included in any toctree
/home/jchatelain/git/tom_base/docs/common/customsettings.rst: WARNING: document isn't included in any toctree
/home/jchatelain/git/tom_base/docs/common/latex_generation.rst: WARNING: document isn't included in any toctree
/home/jchatelain/git/tom_base/docs/common/permissions.rst: WARNING: document isn't included in any toctree
/home/jchatelain/git/tom_base/docs/common/refactoring_roadmap.rst: WARNING: document isn't included in any toctree
/home/jchatelain/git/tom_base/docs/common/scripts.rst: WARNING: document isn't included in any toctree
/home/jchatelain/git/tom_base/docs/customization/adding_pages.rst: WARNING: document isn't included in any toctree
/home/jchatelain/git/tom_base/docs/customization/customize_template_tags.rst: WARNING: document isn't included in any toctree
/home/jchatelain/git/tom_base/docs/customization/customize_templates.rst: WARNING: document isn't included in any toctree
/home/jchatelain/git/tom_base/docs/customization/encrypted_model_fields.rst: WARNING: document isn't included in any toctree
/home/jchatelain/git/tom_base/docs/customization/htmx_tables.rst: WARNING: document isn't included in any toctree
/home/jchatelain/git/tom_base/docs/customization/testing_toms.rst: WARNING: document isn't included in any toctree
/home/jchatelain/git/tom_base/docs/customization/widgets.rst: WARNING: document isn't included in any toctree
/home/jchatelain/git/tom_base/docs/deployment/amazons3.rst: WARNING: document isn't included in any toctree
/home/jchatelain/git/tom_base/docs/deployment/deployment_heroku.rst: WARNING: document isn't included in any toctree
/home/jchatelain/git/tom_base/docs/deployment/deployment_tips.rst: WARNING: document isn't included in any toctree
/home/jchatelain/git/tom_base/docs/examples.rst: WARNING: document isn't included in any toctree
/home/jchatelain/git/tom_base/docs/introduction/about.rst: WARNING: document isn't included in any toctree
/home/jchatelain/git/tom_base/docs/introduction/acknowledging_tom_toolkit.rst: WARNING: document isn't included in any toctree
/home/jchatelain/git/tom_base/docs/introduction/contributing.rst: WARNING: document isn't included in any toctree
/home/jchatelain/git/tom_base/docs/introduction/credits.rst: WARNING: document isn't included in any toctree
/home/jchatelain/git/tom_base/docs/introduction/faqs.rst: WARNING: document isn't included in any toctree
/home/jchatelain/git/tom_base/docs/introduction/programming_resources.rst: WARNING: document isn't included in any toctree
/home/jchatelain/git/tom_base/docs/introduction/tomarchitecture.rst: WARNING: document isn't included in any toctree
/home/jchatelain/git/tom_base/docs/introduction/troubleshooting.rst: WARNING: document isn't included in any toctree
/home/jchatelain/git/tom_base/docs/introduction/workflow.rst: WARNING: document isn't included in any toctree
/home/jchatelain/git/tom_base/docs/managing_data/continuous_sharing.rst: WARNING: document isn't included in any toctree
/home/jchatelain/git/tom_base/docs/managing_data/customizing_data_processing.rst: WARNING: document isn't included in any toctree
/home/jchatelain/git/tom_base/docs/managing_data/plotting_data.rst: WARNING: document isn't included in any toctree
/home/jchatelain/git/tom_base/docs/managing_data/single_target_data_service.rst: WARNING: document isn't included in any toctree
/home/jchatelain/git/tom_base/docs/managing_data/stream_pub_sub.rst: WARNING: document isn't included in any toctree
/home/jchatelain/git/tom_base/docs/managing_data/tom_direct_sharing.rst: WARNING: document isn't included in any toctree
/home/jchatelain/git/tom_base/docs/observing/customize_ocs_facility.rst: WARNING: document isn't included in any toctree
/home/jchatelain/git/tom_base/docs/observing/observation_module.rst: WARNING: document isn't included in any toctree
/home/jchatelain/git/tom_base/docs/observing/selecting_targets_for_facility.rst: WARNING: document isn't included in any toctree
/home/jchatelain/git/tom_base/docs/observing/strategies.rst: WARNING: document isn't included in any toctree
/home/jchatelain/git/tom_base/docs/targets/target_fields.rst: WARNING: document isn't included in any toctree
/home/jchatelain/git/tom_base/docs/targets/target_matcher.rst: WARNING: document isn't included in any toctree
/home/jchatelain/git/tom_base/docs/targets/target_table.rst: WARNING: document isn't included in any toctree

jchate6

Some of these might be non-issues, or resolved when conflicts have been merged.
I'll try to fix a few this afternoon.
Issues:

rachel3834 · 2026-06-15T09:53:08Z

I've added a right-hand-side menu to the custom data processing and data visualization pages, and I've updated the text and figures for the workflow page.

rachel3834 · 2026-06-15T10:04:38Z

Please note I've resolved the conflict with docs/observing/index.rst by including the same new entries further down in the text.

jchate6

Looks great!

rachel3834 added 2 commits March 25, 2026 16:39

docs/update_theme

b5586b1

Updated the theme for the Toolkit's documentation and resolved depend…

c5b5c68

…encies

rachel3834 requested review from jchate6 and phycodurus March 25, 2026 23:45

jchate6 added this to TOM Toolkit Mar 26, 2026

jchate6 moved this to Needs Review in TOM Toolkit Mar 26, 2026

jchate6 added the documentation label Mar 26, 2026

Merge branch 'dev' into docs/update_theme

84dbca7

jchate6 self-assigned this Mar 27, 2026

jchate6 linked an issue Apr 8, 2026 that may be closed by this pull request

Implement new RTD theme #1494

Open

jchate6 approved these changes Apr 8, 2026

View reviewed changes

Merge branch 'dev' into docs/update_theme

eef2fde

jchate6 and others added 15 commits April 9, 2026 12:49

Merge branch 'dev' into docs/update_theme

7572265

Updating from dev

0f9680f

Updated lock

9cedbf0

Revamp landing page and navbar

c1371ca

Revamp configurations pages

95ff72c

Refactor docs for targets

7f28773

Start revamp of observations section

3ed1cfd

Revamp observations page

4ad6a3d

Revamp data section

4f5bcd8

Revamp code section

11e3101

Revamp deployment section

a04121c

Revamp deployment section

67e2e9b

Revise plugins

ea990e4

Revise support and plugins sections

7bd130d

Review and finish docs overhaul

4b05a64

rachel3834 requested a review from jchate6 May 8, 2026 18:33

jchate6 linked an issue May 27, 2026 that may be closed by this pull request

Update TOM Documentation #1493

Open

Merge branch 'dev' into docs/update_theme

f09435c

jchate6 changed the base branch from dev to version-3-0-alpha May 27, 2026 22:57

jchate6 added 2 commits May 27, 2026 16:00

add newline

d783a43

Merge branch 'version-3-0-alpha' into docs/update_theme

c37603e

jchate6 requested changes May 27, 2026

View reviewed changes

jchate6 added 2 commits May 28, 2026 13:31

Merge branch 'version-3-0-alpha' into docs/update_theme

3e3c676

update plugin code location link

514456f

jchate6 self-requested a review May 28, 2026 20:40

jchate6 requested changes May 28, 2026

View reviewed changes

jchate6 reviewed May 28, 2026

View reviewed changes

Comment thread tom_alerts/brokers/alerce.py

rachel3834 added 4 commits June 3, 2026 09:30

Add TOCtrees and fix compilation warnings

abe6dd1

Resolve lint issues

7930f2f

Resolve lint issues

7a38fb6

Revert dataservices to brokers in tom_alerts

3dfc00d

rachel3834 requested a review from jchate6 June 3, 2026 17:54

jchate6 requested changes Jun 10, 2026

View reviewed changes

jchate6 and others added 4 commits June 10, 2026 16:03

clean up toc tree a little

f165b68

Merge branch 'version-3-0-alpha' into docs/update_theme

d58bf89

Merge branch 'version-3-0-alpha' into docs/update_theme

55f435f

Add right-side nav menu; update workflow

7d81c8f

Resolve merge conflicts

cead1ef

rachel3834 requested a review from jchate6 June 15, 2026 10:04

Merge branch 'version-3-0-alpha' into docs/update_theme

22fad8b

jchate6 approved these changes Jun 15, 2026

View reviewed changes

jchate6 merged commit 627ea2b into version-3-0-alpha Jun 15, 2026
22 of 23 checks passed

github-project-automation Bot moved this from Needs Review to Merged (to dev) in TOM Toolkit Jun 15, 2026

jchate6 deleted the docs/update_theme branch June 15, 2026 18:24

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Update to TOM documentation theme#1476

Update to TOM documentation theme#1476
jchate6 merged 34 commits into
version-3-0-alphafrom
docs/update_theme

rachel3834 commented Mar 25, 2026

Uh oh!

jchate6 left a comment •

edited

Loading

Uh oh!

rachel3834 commented Apr 9, 2026

Uh oh!

rachel3834 commented May 8, 2026

Uh oh!

jchate6 left a comment

Uh oh!

jchate6 left a comment

Uh oh!

Uh oh!

jchate6 left a comment •

edited by rachel3834

Loading

Uh oh!

rachel3834 commented Jun 15, 2026

Uh oh!

rachel3834 commented Jun 15, 2026

Uh oh!

jchate6 left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

rachel3834 commented Mar 25, 2026

Uh oh!

jchate6 left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

rachel3834 commented Apr 9, 2026

Uh oh!

rachel3834 commented May 8, 2026

Uh oh!

jchate6 left a comment

Choose a reason for hiding this comment

Uh oh!

jchate6 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

jchate6 left a comment • edited by rachel3834 Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

rachel3834 commented Jun 15, 2026

Uh oh!

rachel3834 commented Jun 15, 2026

Uh oh!

jchate6 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

jchate6 left a comment •

edited

Loading

jchate6 left a comment •

edited by rachel3834

Loading