ipyvuetify docs: new toctree

This is a proposed new totree that uses more the potential of the header bar of pydata-sphinx-theme. All the previous documentation has been moved to "legacy" and will be empied as long as the other sections get filled.

The main objective of the PR is to discuss the structure and also to create the placeholders of each documentation folders to avoid merge conflicts.

Aug 27 '23 21:08 12rambau

Is there a way to redirect the URLs of the old page to the new location in RTD? We have links on github and stackoverflow we don't want to break. Also, for google indexing it's not good that pages which have a good rank now disappear.

Sep 07 '23 15:09 mariobuikhuizen

Usualy I have 2 builds on RDT: "stable" and "latest" if your link is not refereing any specific branch i.e. https://ipyvuetify.readthedocs.io/ then it will point to the default stable. If it's specified "https://ipyvuetify.readthedocs.io/en/latest", then as far as I know, it's too late and I need to code faster

Sep 07 '23 16:09 12rambau

If it's specified "https://ipyvuetify.readthedocs.io/en/latest", then as far as I know, it's too late and I need to code faster

I mean you want to change the page structure in this PR, which is not yet merged and released, so nothing has changed on the internet yet, right?

Sep 07 '23 16:09 mariobuikhuizen

master is already relying on pydata-sphinx-theme but readthedocs latest is still pointing to rdt-sphinx-theme (default). So for a reason I cannot explain (as visitor cannot see the RDT project parameters) it seems latest is not pointing on it.

Sep 07 '23 20:09 12rambau

yeah, see: https://github.com/widgetti/ipyvuetify/pull/238#issuecomment-1693383967. I pointed RTD back to a commit with the old theme, because you were not ready.

But what I mean regarding this PR, we should not break URL's already used in the world by moving/renaming pages.

Sep 08 '23 10:09 mariobuikhuizen

This plugin looks like it would work for adding redirects fr the old URLs: https://pypi.org/project/sphinxext-rediraffe/

Sep 08 '23 11:09 mariobuikhuizen

now I get your point, and then yes rediraffe is the one to go (I think they use it in matplotlib). should I code it in a following up ?

Sep 08 '23 15:09 12rambau

It can be done after we agree on the re-arranging of pages and the new structure is implemented.

Sep 08 '23 15:09 mariobuikhuizen

Would you want me to fill the different sections in this PR? I wanted to keep the scope of my PR reduced (as you suggested) so until this one is merged I cannot move on with the documentation update.

Oct 19 '23 10:10 12rambau

Hi @12rambau, I'm not exactly sure what you are trying to accomplish with this change. We are pretty happy with the structure as is. I also like the main page to be a short summary an image like you made in the previous PR: https://ipyvuetify--277.org.readthedocs.build/en/277/index.html. The main page in this PR is just a tree of text.

Oct 19 '23 12:10 mariobuikhuizen

I'm setting the headers in the top navbar.

I would like to split the current documentation bewteen "getting started" and "advance usage".
In advance usage I would like to add a widget composition example using class.
In the currently empty gallery section I would like to copy/generate real-life examples from the one in the Vuetify examples using ipyvuetify syntax.
The api section will be created automatically by autoapi when it is merged (I'm waiting for https://github.com/readthedocs/sphinx-autoapi/pull/399)

Oct 19 '23 12:10 12rambau

I also like the main page to be a short summary an image like you made in the previous PR: https://ipyvuetify--277.org.readthedocs.build/en/277/index.html. The main page in this PR is just a tree of text.

I followed your advice, I split things. I can't finish the links to #277 until the "gallery" and "api" sections exist.

my plan is (each dot being a PR):

merge this one to get the headers
dispatch already existing content in the "getting started" and "advance usage" sections
add the class composition
merge the autoapi
merge the landing page
generate more meaningful API entries once I'll understand how to add doc info in the vuetify json file (#270)

Oct 19 '23 13:10 12rambau

Oops.. I wanted to check what the docs in master Iooked like and thought that was the last merged PR.

Oct 19 '23 13:10 mariobuikhuizen

my branch is again conflicting with main, @mariobuikhuizen, @maartenbreddels could you provide insight on what I should be doing to move forward?

As you requested I'm making as small PR as possible but without them being merged/reviewed I simply cannot move forward.

Nov 07 '23 12:11 12rambau

Let's first see which new content is added, then see if and how we need to change the structure.

Nov 22 '23 10:11 mariobuikhuizen