docs: new toctree

[12rambau]

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.

[mariobuikhuizen]

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.

[12rambau]

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

[mariobuikhuizen]

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?

[12rambau]

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.

[mariobuikhuizen]

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.

[mariobuikhuizen]

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

[12rambau]

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 ?

[mariobuikhuizen]

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

[12rambau]

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.

[mariobuikhuizen]

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.

[12rambau]

I'm setting the headers in the top navbar.

1. I would like to split the current documentation bewteen "getting started" and "advance usage".
2. In advance usage I would like to add a widget composition example using class.
3. 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.
4. 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)

[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)

[mariobuikhuizen]

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

[12rambau]

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.

[mariobuikhuizen]

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