Use Plone Sphinx Theme

[stevepiercy]

This is a WIP PR to test and develop Plone Sphinx Theme on Documentation, at long last!

Feel free to make suggestions.

Changes

• Inherit all the goodness of Plone Sphinx Theme, including dark mode.
• Removes search customization, including filtering by documentation section. This is currently in flux between the default Sphinx search option and Nuclia search, and I didn't want to spend time on something that might change yet again.
• Removed conflicting static files.

Todos

• Fix Scrollspy on page toc (right-hand navigation). It should insert the active class on the <li> while scrolling, using pydata-sphinx-theme.js.
• Fix "Toggle primary sidebar" hamburger icon when clicked on wide screens. See also:
  • Toggle primary sidebar button pops out that sidebar instead of collapsing it executablebooks/sphinx-book-theme#865
  • Primary nav hamburger icon and page title alignment incorrect, nav does not collapse training#866
• Fix display width of <video> to fit within the main content.
• Remove conflicting static files from submodules so they don't get copied over and clobber the theme's static files.
• Decide between Nuclia, customizing Sphinx's search, or keeping the default search.

Developing tips

To speed up docs build, you can temporarily comment and ignore files.

1. In index.md remove anything from the toctree directive (I moved them out of the directive, then commented them, as comments are not supported within this directive)

2. In conf.py add the following:

    "plone.restapi/**",
    "plone.api/**",
    "volto/**",
    "path_to_exclude/**",

Contributions to improve Plone Sphinx Theme, and therefore all Plone documentation sites, are gratefully accepted.

---

📚 Documentation preview 📚: https://plone6--1770.org.readthedocs.build/

[davisagli]

The build failed with:

Theme error:
An error happened in rendering the page _inc/_continuous-integration.
Reason: UndefinedError("the template '../macros/buttons.html' (imported on line 3 in 'sections/header-article.html') does not export the requested name 'render_label_input_button'")

[stevepiercy]

Sorry about that. I forgot to actually delete the files instead of just moving them temporarily. Fixed in c2885d7.

[stevepiercy]

We need to decide which search option to use going forward. The default Sphinx search is the default for Documentation at this moment.

Default Sphinx search

• No custom setup required.
• No maintenance needed.
• Can be used locally without an Internet connection.
• Search results are OK.
• Available now.

Custom Sphinx search (based on the default Sphinx search)

• Requires trivial custom setup.
• Needs to be maintained for every release of Sphinx where they update the JavaScript (often without notification), or whenever we want to use and adapt filtering by sections of the documentation. Training uses this customization.
• Can be used locally without an Internet connection.
• Search results are OK and can be filtered per section.
• Needs to be updated before it can be used.

Nuclia

• Requires moderate custom setup with API key.
• No maintenance needed.
• Requires an Internet connection to retrieve search results.
• Has the potential to offer better search results with a customization. See https://docs.nuclia.dev/docs/rag/search-strategy
• Still needs some custom configuration work, including changing to scraping local HTML, and improving styles.
• Has AI feature that is pretty nifty. Example: https://plone-training--792.org.readthedocs.build/search.html?q=How+to+install+a+Volto+add-on#
• Preview URL: https://plone-training--792.org.readthedocs.build/
• Open PR: Integrating Nuclia Widget training#792.

[stevepiercy]

Two more Nuclia notes:

• @ebrehault and @bloodbare work at Nuclia https://nuclia.com/company/.
• The integration was part of a GSoC project in 2023.

[davisagli]

@stevepiercy I'd be fine with using a more basic search option in order to un-block moving forward with this theme -- but it doesn't seem to be working on the current deployment at https://plone6--1770.org.readthedocs.build/

Filtering by section and Nuclia-powered results are both nice to have, if someone's willing to do the work to set it up.

[stevepiercy]

@davisagli it's my intent to move ahead with the new theme with the default Sphinx search option soon.

I prefer the Nuclia search option in the long-term.

Right now I'm working on two issues with Plone Sphinx Theme, which I added to the checklist above. I found the fix to scrollspy, and will push that after I finish testing. For the Toggle primary sidebar issue, I think it exists upstream in Sphinx Book Theme, at least in my testing. We'll see if someone else can reproduce that issue upstream. I think it has to do with how its own upstream theme, PyData Sphinx Theme, recently moved that item into a different section of its theme.

[davisagli]

Nitpick: I'd prefer if the social media icons were somewhere less prominent than the top of the navigation column.

[stevepiercy]

Yeah, the icons belong in the page content footer. I've pushed another commit to move them there, but I need to apply a style in Plone Sphinx Theme.

[stevepiercy]

@davisagli done and forced rebuilt preview: https://plone6--1770.org.readthedocs.build/

[stevepiercy]

I created a new issue #1773 to track the "Toggle primary sidebar" item.

The search for now will be the default Sphinx search. If someone wants to customize the JavaScript or work on Nuclia, I'd welcome either or both.

This PR is blocking rendering of new required features in the docs, so I'm going to merge now.

[stevepiercy]

GitHub is rate limiting linkchecking, and has stalled. Merging.