Change documentation theme

[adamjstewart]

Issue

We've been using pytorch-sphinx-theme since the start of the project, but it contains a number of known issues and is barely maintained. We should consider switching to a modern theme with fewer bugs and better support.

Fix

I was originally planning on using trojanzoo-sphinx-theme but it looks like this is also unmaintained now. I don't think I have the skills or expertise to maintain my own fork of either. We should look into popular themes and choose one that looks cool. Can people propose themes and link to examples on this issue?

[adamjstewart]

PyTorch Lightning uses a fork of pytorch-sphinx-theme called lightning-sphinx-theme. However, this fork seems to have some of the same problems (no PyPI releases).

[Thakor-Yashpal]

Can I address this issue?

[adamjstewart]

Sure! You should probably start by proposing a few themes that don't look too different from our current theme or are popular in ML. Once we narrow it down, you can open a few example PRs that change the theme and we can see what they look like.

[Thakor-Yashpal]

I've been exploring Sphinx themes, and I think the Sphinx-Rtd theme (the Read the Docs fork) might be a good fit for us.

It's familiar, has more customization options, and is still actively maintained.

Would you be open to trying it out? I can set up a test project and show you how it looks in our documentation.

Let me know your thoughts!

[adamjstewart]

Sphinx-rtd-theme is a bit generic and isn't widely used by the PyTorch community. I'm not opposed, but I'm hoping to find something a little fancier. Is there anything else closer to our current theme?

[Thakor-Yashpal]

Thanks for the suggestions! I'm leaning towards Furo (with careful customization) or Material for Sphinx. I think Furo's design is a good starting point, and I'm confident I can make it match the PyTorch theme's overall feel. I'll start working on customizing Furo, and if I run into any challenges, I'll definitely come back to you for more advice.