docs: change the theme

[12rambau]

@mariobuikhuizen, I would like to work on the documentation and update the template that is used. my objective are the following :

• use the pydata-sphinx-theme (because thats my favorite for sphinx)
• refactor the structure of the documentation to expose the API
• try to pull information from the vuetify API
• use the widgetti logo

This PR is just a demo using pydata-sphinx-theme, is there a chance to see this PR merged if I continue working on it ?

Related to #268

[maartenbreddels]

I like the theme and your plans!

[12rambau]

requires #240 to move forward

[12rambau]

@mariobuikhuizen I'll stop this PR here to avoid a too big scope. what is cover is the following:

• adapt deps to use the pydata-sphinx-theme
• adapt conf.py accordingly (and remove automatically generated comments that are not there anymore since Sphinx 6)
• refactor the toctree to make it conform to pydata-sphinx-theme

work that I will do in the following-up PR: reorder pages to make better use of the theme sidebars.

In case you think this should not be put in production yet (to which I agree) you should publish a stable version of the docs in RDT and link it in the readme. I think you need to make a GitHub release for that, else you can manually trigger the rebuild of stable. Let me know what you prefer.

[mariobuikhuizen]

Thank you for not increasing the scope further! Can you please remove the changes not related to changing the theme?

[12rambau]

I scanned the modifications again and I see 2 potential candidates:

• drop of requirements.txt (not used anywhere since build: use nox for tests and docs  #240)
• drop the extensive comments present in the conf.py when I refactored it to include the pydata-sphinx-theme config.

Which should I remove ?

[mariobuikhuizen]

To be clear, those changes are good to do, but not in the PR called "change the theme".

[12rambau]

then the answer is "both of them" 😄 Understood, I'll create other PR for them

[mariobuikhuizen]

Thank you 😄

[12rambau]

let's wait for the test completion but normally I'm good to go

[mariobuikhuizen]

One of the advantages of keeping changes as concise as possible is less chance of conflicts. #272 also changes code formatting: 32273a0#diff-85933aa74a2d66c3e4dcdf7a9ad8397f5a7971080d34ef1108296a7c6b69e7e3R25 , which leads to a conflict here.

Also, I see now that that PR removes master_doc = "index", this is certainly something different than removing comments.

[12rambau]

conflict resolved. master-doc is an ignored parameter if there is an "index.rst" next to conf.py. I didn't even realized I removed it.

[mariobuikhuizen]

If I check the build on: https://ipyvuetify--238.org.readthedocs.build/en/238/ I don't see the new theme applied

[mariobuikhuizen]

Much cleaner diff now! 😄

[mariobuikhuizen]

Thanks!

[mariobuikhuizen]

In case you think this should not be put in production yet (to which I agree) you should publish a stable version of the docs in RDT and link it in the readme. I think you need to make a GitHub release for that, else you can manually trigger the rebuild of stable. Let me know what you prefer.

Turns out older branches don't build anymore, so we're forced to put it in production. I trust it runs well.

[12rambau]

ok I'll try to be as fast as possible to make the follow-up PR to have a more readable documentation ASAP

[mariobuikhuizen]

What less readable now?

[mariobuikhuizen]

Come to think of it I can also point the stable branch to just before the theme change commit. That will give more time to make your changes.

[mariobuikhuizen]

Production docs are back to the old theme.