DOC: reorganisation of the documentation?

[jorisvandenbossche]

I think the documentation can use some reorganisation.

The current structure looks like this (updated with status of jan 2017):

    What’s New
    Installation
    Contributing to pandas
    Frequently Asked Questions (FAQ)
    Package overview
    10 Minutes to pandas
    Tutorials
    Cookbook
    Intro to Data Structures
    Essential Basic Functionality
    Working with Text Data
    Options and Settings
    Indexing and Selecting Data
    MultiIndex / Advanced Indexing
    Computational tools
    Working with missing data
    Group By: split-apply-combine
    Merge, join, and concatenate
    Reshaping and Pivot Tables
    Time Series / Date functionality
    Time Deltas
    Categorical Data
    Visualization
    Style
    IO Tools (Text, CSV, HDF5, ...)
    Remote Data Access
    Enhancing Performance
    Sparse data structures
    Caveats and Gotchas
    rpy2 / R interface
    pandas Ecosystem
    Comparison with R / R libraries
    Comparison with SQL
    Comparison with SAS
    API Reference
    Internals
    Release Notes

which is a huge list that is somewhat unclear and difficult to navigate.
It is maybe also an issue that will have to go hand in hand with a better navigation provided in the html theme of the docs.

[ghost]

You are our 6000th issue. Here's a 🍭

[ghost]

For unrelated reasons I've been reading up on what makes good documentation.
The following http://jacobian.org/writing/what-to-write/ is relevent and the companion
posts are a pretty good read as well.

We refreshed the sphinx theme nearly a year ago #3272, what did you have in mind?

[jtratner]

@jorisvandenbossche - you've had good instincts so far so definitely go with it.

Maybe we could change the front page to be a few basic examples of how you use pandas and move changelog / mailing list / other stuff off the front page of the docs.

[jorisvandenbossche]

What I am thinking about here in this issue, is a more nested structure (instead of the current flat structure). For example:

• Installation
• Getting started with pandas (now: overview, 10minutes)
• User guide:
  • Data Structures
    • basic functionality
  • Indexing and selecting data:
    • indexing
    • advanced indexing
    • multi-index
  • computational
  • missing data
  • data manipulation
    • reshaping
    • merging
    • groupby
  • graphics/visualisation
    • plotting with matplotlib
  • Input/output (importing and exporting data)
    • text, csv
    • hdf5
    • sql
    • ... (all the other formats)
  • Time Series / Date functionality
    • timeseries
    • timedelta
  • advanced
    • improving performance
    • sparse
• Reference guide (/api)
• Developer documentation
  • Contributing to pandas
  • Internals
• Additional resources (Tutorials, External Resources, Videos and Talks)
• Ecosystem
• Releases (whatsnew, release)

The above is just an example to give the general idea. I think some current pages are still missing in this example, and the different parts in the User Guide can certainly be improved.
And such a more nested structure will also only work with a more powerful sphinx theme that allows a better table of contents (xref #15556).

Do people think this would be an improvement? (general idea, not specific subdivisions)

[jreback]

generally flat is better than nested. BUT we have a lot of docs and its hard to navigate now :>

Further this will split really long doc pages (e.g. io.rst)

[mroeschke]

cc @datapythonista

[afeld]

Closing in favor of #24499.