[blocked] Switch to Furo Sphinx theme

[Eric-Arellano]

Rustworkx is not really a part of the Qiskit ecosystem. While Qiskit uses it, it is independent of the Qiskit / QC ecosystem.

There has been tension with using qiskit_sphinx_theme because that theme is optimized exclusively for the Qiskit Ecosystem. For example, it adds a top nav bar to navigate around Qiskit.org. Rustworkx doesn't want that, so it's been overriding the HTML template to remove the top nav bar. But that risks changes to qiskit_sphinx_theme breaking the override, such as CI recently failing.

Instead, it's simpler to use Furo directly.

(Why Furo? This is the direction qiskit_sphinx_theme is going too. See Qiskit/qiskit_sphinx_theme#232 for the motivation.)

[coveralls]

Pull Request Test Coverage Report for Build 4918047208

• 0 of 0 changed or added relevant lines in 0 files are covered.
• 1 unchanged line in 1 file lost coverage.
• Overall coverage decreased (-0.007%) to 97.078%

---

Files with Coverage Reduction	New Missed Lines	%
src/shortest_path/all_pairs_dijkstra.rs	1	99.27%

Totals
Change from base Build 4731978762:	-0.007%
Covered Lines:	14386
Relevant Lines:	14819

---

💛 - Coveralls

[IvanIsCoding]

Well I don't oppose this, PyTorch's theme is ok but it has its quirks (see #606). So if you say that Qiskit's Sphinx Theme is no longer going to support us that is fine.

I do recommend checking PyData's Sphinx Theme though. Many scientific software libraries use the theme including NetworkX, NumPy, and Matplotlib. So it should be a theme that many of our users have seen before which puts it above Furo in my opinion

[Eric-Arellano]

So if you say that Qiskit's Sphinx Theme is no longer going to support us that is fine.

To clarify, Qiskit Sphinx Theme is happy to continue the project using its theme. But, Matthew wants to make changes different than most Ecosystem projects, such as removing the top nav bar. That is 100% allowed, only it increases your maintenance burden. So, instead, Matthew and I thought a simpler solution would be to migrate to Furo directly.

I do recommend checking PyData's Sphinx Theme though

Thanks for the suggestion! Y'all are free to use whichever theme you prefer. For qiskit_sphinx_theme itself, the plan is Furo after closely investigating the themes in https://sphinx-themes.org, including PyData Sphinx Theme. I think PyData is nice, but we went with Furo because its layout works better for our needs, such as the top nav bar, and we all liked the design more.

We can't yet use Furo in this PR because we need to add support for the "previous versions" feature. I am working on that as part of qiskit-sphinx-theme. Then, we would copy and paste that code into this PR here for you all.

If you go with PyData, you wouldn't be able to as easily re-use that work because e.g. the styling will be different. (But you could use its built-in support from https://pydata-sphinx-theme.readthedocs.io/en/stable/user_guide/version-dropdown.html)

So it should be a theme that many of our users have seen before which puts it above Furo in my opinion

Fwiw, Furo is used by Pip, Black, and Attrs. So I think users will have familiarity with both.

But also, I don't think familiarity is necessarily that important of a criterion. More important are things like how easy it to use, if it's fully mobile responsive, how accessible it is for disabilities, if it meets your design expectations, etc.

[Eric-Arellano]

We had our first design session for the Ecosystem Theme of qiskit_sphinx_theme and I think it's plausible it will be good enough for this repo to want to use it. For example, we are thinking we should probably not show the top nav bar, which is a complaint with the current theme. See #866

So I'm going to close #866 for now. We can always revive the PR.