Split out data documentation section into separate subpages

[joelostblom]

Follow up on what was done for spatial data here #2750 (comment).

[binste]

Started working on this but I'm facing an issue with the sphinx toctree directive. Maybe @joelostblom or @mattijn have some idea how to resolve this?

I tried to replace the still existing data.rst with data/index.rst. To do this, I set data/index.rst as the start page of the user guide in index.rst:

.. toctree::
   :maxdepth: 1
   :hidden:

   Getting Started <getting_started/overview>
   User Guide <user_guide/data/index>
   Examples <gallery/index>
   API Reference <user_guide/API>
   user_guide/ecosystem
   releases/changes

But the issue is now that in data/index.rst I need to include the toctree directives for the User Guide sidebar as well as the toctree for the data subpages.

.. toctree::
   :maxdepth: 1
   :caption: User Guide
   :hidden:

   self
   ../encodings/index
   ../marks/index
   ../transform/index
   ../interactions
   ../compound_charts
   ../scale_resolve
   ../times_and_dates
   ../customization
   ../configuration
   ../saving_charts


.. toctree::
   :maxdepth: 1
   :caption: Advanced Usage
   :hidden:

   ../internals
   ../importing
   ../display_frontends
   ../custom_renderers
   ../data_transformers
   ../large_datasets

.. toctree::
   :maxdepth: 1
   :hidden:
   
   dataframe
   url
   spatial
   generator
   dict

Having all of these toctrees with multiple levels seems confusing to sphinx. It just places dataframe, url, etc. at the end of "Advanced Usage":

Found sphinx-doc/sphinx#2103 which seems related but does not provide a solution.

Looking at other packages, I did not yet find an example of a documentation which achieved what we want to do here. For example in the matplotlib documentation, they have a landing page for e.g. Plot types which is not the same as the first sidebar entry "Basics". We could also do that, i.e. a "User Guide" landing page, but I don't find it very useful and would prefer to directly start with the "Data" page as was the case so far.

If you're not familiar with a workaround, I'd suggest that I revert the structure back to having one "Data" page without subpages.

[mattijn]

I also tried a few options but was unable to find a solution. For now, reverting to a single page seems to be the best option. However, if you have any other ideas that could resolve the issue without resulting in a large, single page, I'm open to those as well.

I noticed that pandas also uses a large, single page for their documentation, so it might not be a big deal. See for example this page https://pandas.pydata.org/docs/user_guide/dsintro.html.

[joelostblom]

I don't know of a good solution to this either, so thanks for reverting to a single page again. I think the current page is quite long so my vote would be to still keep this issue open as a low priority item in case there is a solution for splitting it into multiple pages in the future.

[dangotbanned]

@joelostblom I'm closing this as completed by #2781

We can track the remaining work in #2796