Docs reorganization

[quaquel]

Quick test based on a discussion in #2448. This reorganizes the docs by moving items from the top menu bar into the left-hand section navigation column.

I have gone for a rather radical approach and this is really proof of concept only at the moment. The top menu now only has overview, getting started, and API. All other stuff have been added to the getting started section. The getting_started.md file needs to have text in addition to the toctree to serve as a proper landing page.

I also think the migration guide might be better of in the top menu bar so its easy to find for existing users.

@EwoutH let me know your thoughts.

[EwoutH]

Thanks for opening the PR. Looking at the rendered docs, I’m a bit conflicted.

I also think the migration guide might be better of in the top menu bar so its easy to find for existing users.

The challenge is that you can make this argument for a lot of the resources. Let me think about this a bit and maybe look at a few other libraries how they do it.

One idea is to (almost) abolish the top bar and have a semi permanent left side bar, since that fits more (but also takes more space).

[quaquel]

One idea is to (almost) abolish the top bar and have a semi permanent left side bar, since that fits more (but also takes more space).

That might require changing to a completely different rtd style.

[EwoutH]

Rome isn’t built in a day (unfortunately).

I must say I find these docs very clean and clear in their layout, I wonder which brilliant maintainer designed those 😇

[tpike3]

This is a good discussion thanks @quaquel

I like the pydata theme but am not necessarily opposed to other approaches.

Some thoughts would be

• Agree to a simpler lay out with groupings
• I would argue we can get rid of mesa packages, that really never went anywhere; maybe work with other groups like rbb4abm ??
• Maybe instead of examples, we should call it gallery like Networkx and in this case we could merge How to and Examples in one page.

Just some off the top of the head thoughts. I am not tied to anything.

[quaquel]

Thanks @tpike3 for the feedback. I have a few ideas that I'll try to implement later today that offer a bit of a middle ground between the current docs and this radical approach.

I would argue we can get rid of mesa packages, that really never went anywhere; maybe work with other groups like rbb4abm

Happy to remove it for now. I'll check with my colleagues who are involved in rbb4abm what might be possible.

[quaquel]

I made a few changes. First, I moved examples and the migration guide out of the getting started page. They are now back in the top bar menu.

Second, I figured out how to get stuff in the left hand column. This is populated based on a toctree directive, which can also be declared hidden. See here is what it now looks for the examples:

Personally I think this is moving in the right direction. I want to add some text to the getting started page. Probably have a subsection called tutorials, with 2 tutorials for now. This creates space for more tutorials in the future. Again, feedback is welcome.

[quaquel]

Mesa Overview might be combined with the getting started part. This would remove one more item from the top row that is only a single page and thus is not really a section with several associated pages. Some of the material might be used to fill out the getting started landing page, while the rest might be a good follow up in between tutorials and the full gory details of the API docs.

[EwoutH]

That's looking great!

Second, I figured out how to get stuff in the left hand column. This is populated based on a toctree directive, which can also be declared hidden.

That's good to know. Looking through it, I think the Section Navigation (left column) can be hidden in most cases (by default). Navigation could go through the top bar and the main Getting Started, Examples, etc. pages themselves.

[quaquel]

I have done some further reorganization as discussed. So, I combined the old overview page and the new getting started idea. I reorganized the material a bit. So, the structure is now: tutorials, examples that ship with mesa, mesa packages overview, further resources.

I also updated the best practices a little bit wrt random.

This is ready for a proper review

[EwoutH]

Thanks for your patience. Overal looks really good, clear improvement over what we had. Few minor comments.

[tpike3]

Thanks @quaquel!