ReadtheDocs Section Navigation

[tpike3]

Describe the bug
Section Navigation needs improvement, reorganization, or removal. It lists the first 6 of 11 tutorials and the best practices, which is nonsensical (appreciating I did the last big docs updates that produced this result)

Also the Source Ccode sections needs the extra c remove

Expected behavior
Docs navigation should be easy and intuitive for uses to navigate

To Reproduce
Go to https://mesa.readthedocs.io/stable/overview.html and see section navigation

This section navigation is also apparent in Getting Started page, overview on section navigation carries redundant information as shown here when you expand overview.

Now how to "fix it" is another question.

My thought right now is we do not need a section navigation. We have top and "on this page" navigations. Loss would be fast links to the tutorial menu, which has no page.

Proposed Way Forward:

• Add a tutorial page that lists the tutorials
• Add Tutorials to the top menu
• Remove Section Navigation

[quaquel]

Not sure I understand. According to you what should be in the section navigation?

[unnati-jaiswal24]

Hi, I have seen the problem with the navigation section on the overview.md page which is showing the tutorial sections instead of the overview sections. The sidebar should show the current page we are in ,in overview.md file to make navigation easier for users.

I am interested in working on fixing this issue. please assign this issue to me so I can start seeking to sidebar configuration, toctree directives, and related theme settings to resolve it.

Thanks

[quaquel]

I am not sure I agree. At the top of the page, you can see "Getting Started", "Overview", etc. so it is redundant to also show this on the left hand side. The section navigation shows the content within a given entry. So, e.g., within getting started or within overview. As it currently does.

[dhiraj-143r]

I saw you’re working on this issue. Should I also work on it ?

[quaquel]

It's not yet clear exactly what the issue is, so let's first get a clarification from @tpike3

[dhiraj-143r]

ok

[dhiraj-143r]

I will be waiting for the clarification

[tpike3]

Apologies, was in a bit of a rush when I wrote this. To @quaquel points there is the "on this page" in the upper right, I made clarifications to the issue, and am repeating here.

Improved issue discussion:

Section Navigation needs improvement/ reorganization/ removal. It lists the first 6 of 11 tutorials and the best practices, which is nonsensical (appreciating I did the last big docs updates that produced this result)

This section navigation is also apparent in Getting Started page, overview on section navigation carries redundant information as shown here when you expand overview.

Now how to "fix it" is another question.

My thought right now is we do not need a section navigation. We have top and "on this page" navigations. Loss would be fast links to the tutorial menu, which has no page.

Proposed Way Forward:

• Add a tutorial page that lists the tutorials
• Add Tutorials to the top menu
• Remove Section Navigation

Also the Source Ccode sections needs the extra c remove

[dhiraj-143r]

ok I got it

let me work on it

[quaquel]

@tpike3, I am still not sure I fully understand. I do see that the section structure getting started & overview is messed up. That is, the section structure is not consistent across all parts of the section, and the breakdown under overview is also a mess. In general, it's strange that "getting started," which is in the top banner, has "overview," which is also in the top banner, as a section.

I open a draft pr to try a few things. The resutling docs can be found here: https://mesa--2883.org.readthedocs.build/2883/getting_started.html

What I have done is remove the toctree from getting_started.md, and corrected the toctree in overview.md. Let me know if this is in line with what you had in mind.

[tpike3]

@tpike3, I am still not sure I fully understand. I do see that the section structure getting started & overview is messed up. That is, the section structure is not consistent across all parts of the section, and the breakdown under overview is also a mess. In general, it's strange that "getting started," which is in the top banner, has "overview," which is also in the top banner, as a section.

I open a draft pr to try a few things. The resutling docs can be found here: https://mesa--2883.org.readthedocs.build/2883/getting_started.html

What I have done is remove the toctree from getting_started.md, and corrected the toctree in overview.md. Let me know if this is in line with what you had in mind.

Thanks @quaquel, that absolutely solves the immediate issue I brought up and apparently I kicked a bit of a hornets nest here😬

To your larger points though, the section structure and overview across the readthedocs is inconsistent. Using the markdown/html headers as a guide.

The h2 sections on Getting Started are

• Overview
• Tutorials
• Examples
• Further Resources

But the top banner is

• Getting Start (h1)
• Overview (h2)
• Examples (h2)
• Migration Guide (h3)
• API (h3)

Way Forward (for discussion)
I would say lets merge @2883 just to fix the immediate issue. However, this does beg the question, what strategy should we use to update the read the docs structure. Off the top of my head I came up with 2 strategies.

1. Check the read the docs analytics (but this accepts current structure)
2. What are we are trying to accomplish with the read the docs.

Using 2, I would say the read the docs has three goals

1. Users can use and understand Mesa as quickly as possible (i.e. lowest bar to entry as possible)
2. Users have ample resources to reference to make their own models (i.e. easy to become a repeat user)
3. We are encouraging the creation of a community and the building and sustainment of the ecosystem (i.e. expanding the community)

To this end I would say we would need some pages created but propose the following top banners which should drive the overview page:

1. Users can use and understand Mesa as quickly as possible (i.e. lowest bar to entry as possible)
   • Top Banner link ("Learn Mesa" / "Getting Started" ?) needs rewrite/clean up
   • Page would consist of:
     • Overview
     • Tutorials
     • Best Practices
     • Basic Examples
2. Users have ample resources to reference to make their own models
   • Top Banner Link ("Mesa Advanced" ? ) Need a a page
   • Page would consist of
     • Advanced Examples
     • Example Repo
     • Mesa-Geo
     • Mesa-Frames
     • Mesa-LLM
3. We are encouraging the creation of a community and the building and sustainment of the ecosystem
   • Top banner link (Community ?) Needs a page (welcoming entry)
   • Page Would consist of:
     • Opening line of open source dynamics and ping us on Matrix if no response
     • Contributors Guide
     • GSOC Guide
     • Matrix links
     • Repeat links to Mesa Ecosystem

I would also have banner links to API and Migration.

I am not tied to any of this and our readthedocs structure is a nontrivial question.

[dhiraj-143r]

can i work on this ?

[quaquel]

The main problem has already been addressed, but we haven't agreed yet on future improvements. Any thoughts are welcome but it makes sense to first agree on how to address the reorganization before opening any PR.