Theme update

[erogluorhan]

This is now a working sphinx-pythia-theme update with the followings:

• sphinx_pythia_theme/layout.html updated to keep our website's layout/style almost 100% unchanged by using the layout/style changes in the parent sphinx_pythia_theme
• Keep using our sphinx_pythia_theme/footer.html (though with some updates in it) to create our custom Pythia footer using the parent's footer_start only
• src/scss/sphinx-pythia-theme.scss updated (a lot of !important used) to keep Pythia's custom colors and styles working with the changes in the parent themes
• A lot of layout / style related config and html_theme_options changes here and there
• sphinx-book-theme>=1.0.0
• Python=3.11
• Sphinx=7.2.6 tested
• Infratstructural housekeeping (e.g. CI workflows, etc.)
• Emails, copyright year, etc. updated

[agoose77]

This can be replaced by built in concurrency - https://github.blog/changelog/2021-04-19-github-actions-limit-workflow-run-or-job-concurrency/

[erogluorhan]

Thanks a lot; wasn't aware of this key. Just went over its docs and found it a bit more complicated than what is currently here (e.g. defining groups, specifying if concurrency for PR numbers, etc.), though please feel free to push the change if you'd like that better (and maybe find it more useful than the one here).

If I were to implement it, should it look something like this:

concurrency:
  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
  cancel-in-progress: true

[agoose77]

Sorry, I didn't see this outstanding question. Yes, the concurrency group just needs to be non-unique for the same PR e.g.

group: 'docs-${{ github.head_ref || github.run_id }}'

This ensures that if the run doesn't have a head_ref (non-PRs), then it falls back to a unique identifier.

[erogluorhan]

No worries! FYI: The theme update is working now, and its proper functioning (with a few non-vital issues) has been confirmed through tests by a few team members. It is a bit time sensitive before our upcoming community event; hence, I'd like to get it merged and go forward to be used by our portal.

I've created a new issue though to address this suggestion.

Thanks very much for all your help and review!

[erogluorhan]

An FYI: The Pythia portal nightly build with this updated theme built successfully; however, we will need to inspect its artifact and maybe perform additional tests to investigate if the results of the theme is good for actual deployment.

[jukent]

@erogluorhan This looks pretty reasonable to me and I'm glad that it is working. However it's possible there are things I don't understand well enough to catch. Let me know if you want to do a walk through of the changes.

Also I'm wondering if there are any lessons you learned while working on this that could go into some internal documentation for ease of future updates.

[erogluorhan]

Hey @jukent , thanks for that! Yes, I can give you a walk through of the current state anytime. Even though I marked this as review-ready, it was more for bringing it to attention of everyone in the loop, and get some feedback/help from the more experienced (since I am not at all experienced on this work).

The current state of it seems good about that we were able to get Sphinx, theme, and dependency packages up & running with their unpinned versions. However, there is still work to do on getting this new version of the theme to reflect all the features listed here. Currently, I am looking into layout.html to display the banner page layout, hide the right ToC, etc. in Pythia portal's homepage properly as before.

[erogluorhan]

FYI: This is where I am as of now. You can download it and check out _build/html/index.html locally.

[jukent]

The navbar menu links' color is set to --pst-color-text-muted. I think this is too light. On the site now, they're a dark gray that turns teal when hovered over.

The underlining of the link when hovering over it is also new, but I think helpful.

Great work on this! I know it was really a big push.

[jukent]

Steps taken to build.

From Portal or Foundations repository:

git fetch --all
git branch -r
git checkout -b theme upstreme/try_updated_theme
conda env create -f environment.yml

Then from the sphinx-pythia-theme repository:

conda activate pythia-book-dev (for foundations) or conda activate pythia (for portal)
pip install -r requirements.txt
python -m pip install . --no-deps

Then in Portal:

conda activate pythia
pip install git+https://github.com/ProjectPythia/sphinx-pythia-theme.git@theme-update
cd portal
make html
open _build/html/index.html

Or in Foundations:

conda activate pythia-book-dev
pip install git+https://github.com/ProjectPythia/sphinx-pythia-theme.git@theme-update
jupyter-book build .
open _build/html/index.html

[erogluorhan]

How does it look now, @jukent? (screenshot is from my local but I can push it if it is liked)

[jukent]

Yeah that looks great! If you push the commit I'll re-test my build.

[jukent]

Thanks Orhan for all of the hard work that went into this. These changes seem sensible and we've had several chances to look at the Html together. Thanks for updating the CSS to make the foundations navbar more legible.

LGTM! I think this issue is holding up another PR and plenty of other book dev work. Thanks again!

[ktyle]

@erogluorhan and I are meeting to chat at 11AM CDT today (@jukent feel free to join as well!), but I agree that we're on the right track and it will be great to get this merged soon since it will resolve a lot of existing issues. Some things I notice, cookbook-related at least, include:

1. Some cookbooks have Jupyter notebooks whose output does not properly fit in the main (center) panel. In the cases I've tested so far, they have all involved Holoviz/Bokeh-based visualizations.
2. At least on my MacBook Air, the left and right panels are too wide, yet the text does not fully occupy the panel.

[erogluorhan]

Hey @agoose77 please see this discussion about the theme update. Thanks for everything!