Update Documentation project

[ChucklesOnGitHub]

This is a mega-issue to join up all the little ones scattered about, and make a roadmap. We can add issues once we start each stage.

1. Modern pages deployment - Done
Brandon is done migrating to the artifakt actions as opposed to separate github pages branches.

2. Conf.py uniformization
There have been individual changes in different repos, can we combine and have a single conf.py that works for them all? It also needs to get cleaned up, and leave only what is necessary. The main issue here will be the onix-docs conf.py

• Navbar is almost agreed on, that these are addressed:
  Change Twitter for Bluesky #12
  Uniformize Purchase/Download/Open Ephys #11
  Where should GitHub icon point to? #10
  External link to "Documentation Landing Page" with all doc sites listed #5

• Set a way to periodically check for sphinx and pydata theme latest versions, but make the case for not automatically updating in case things break.

• Figure out dark mode
  Dark mode not working across all documentation pages #9

-Port all changes back to doc-template
#7

3. html best practices

• Clean up css to get rid of Important! and similar
  Style consistency across docs #3

4. Is a one-source-of-truth and template approach possible

• We discussed including conf.py and the .css theme overides as a submodule in a standalone workflow, and linking all the repos to the docs-template repo that would hold this.
  --For variable stuff such as linkchecks, the conf.py would need to refer to a specific file within the local repository
  -- Figure out what to do with shuttledrive-docs and twister3-docs that were forked

5. PR Preview action

• Implement https://github.com/rossjrw/pr-preview-action or similar.

[cjsha]

hey just saw this, thought i'd give my 2c

4. Is a one-source-of-truth and template approach possible

I think it's absolutely the way to go about implementing point 2.

--For variable stuff such as linkchecks, the conf.py would need to refer to a specific file within the local repository

For the specific example of linkchecks, it might be ok for them to have share that variable. But yeah there are conf.py variables that should not be shared across the repos. The repo-specific conf.py can import the "global" submodule conf.py and then define the variables that are unique to the repo and overwrite any variables that need to be overwritten.

-Port all changes back to doc-template

Changes should be back-ported to doc-template insofar as the docs-template is set up for SSOT in the same way as the rest of the docs are.

Set a way to periodically check for sphinx and pydata theme latest versions, but make the case for not automatically updating in case things break.

I think we should just keep an eye on and subscribe to notifications of release updates from the pydata sphinx theme repo and update the theme according to when there are updates that we think are worth adopting.

To prevent things from breaking, I propose the SSOT repo has a "kitchen sink" docs site that contains all the elements we use across the docs (tabs, cards, wavedrom, dropdowns, images, figures, rubrics, etc., navbar, a few different pages some of which are nested, ordered and unordered lists, etc.) so that when we want to make changes to the styles/theme, it will facilitate making sure that all the elements used across the docs are maintained. I think this should be maintainable as long as we move away from using .. raw:: html directives.

---

For me the question is, what is the action that happens when the ssot is updated? Are the deployed docs repos automatically updated?