Restructure navigation

[AA-Turner]

This PR restructures the top-level navigation. I used the Diátaxis framework for general design guideance and several homepages of popular projects (e.g. NumPy) for applied navigation.

I've organised as follows as a suggestion:

• 'Overview' -- all example notebooks, and the two prose documents explaining the background and context of HARK -- this fits the 'explanation' category of Diátaxis
• 'Reference' -- this is the current reference section
• 'Guides' -- this is currently the quick start, installation, and contribution guides, but could grow to encompass tutorial style content

The notebooks were somewhat challenging to classify as tutorial (learning-first) vs explanation (understanding-first), but for ease I've put them all in explanation for now. Tutorial is the major missing Diátaxis category currently.

A

cc: @MridulS

(this PR is based on top of #1301; please review that one first!)

[review-notebook-app]

Check out this pull request on 

See visual diffs & provide feedback on Jupyter Notebooks.

---

Powered by ReviewNB

[codecov]

Codecov Report

Patch and project coverage have no change.

Comparison is base (09f1843) 72.55% compared to head (510c992) 72.55%.

Additional details and impacted files

@@           Coverage Diff           @@
##           master    #1302   +/-   ##
=======================================
  Coverage   72.55%   72.55%           
=======================================
  Files          78       78           
  Lines       13009    13009           
=======================================
  Hits         9439     9439           
  Misses       3570     3570           

☔ View full report in Codecov by Sentry.
📢 Do you have feedback about the report comment? Let us know in this issue.

[MridulS]

Thanks @AA-Turner!

Urghh, looks like the #1301 merge created too many merge conflicts. Could you rebase and push?

[AA-Turner]

Done!

[MridulS]

Some notes:

The references section behave differently for the tools sections and the models section (Not sure if it's a local issue for me). The sidebar on left goes away for tools section.

While we are on diataxis, can we get the pretty blocks like https://docs.scipy.org/doc/scipy/ for the homepage? (Doesn't need to happen in this PR)

[AA-Turner]

The references section behave differently for the tools sections and the models section (Not sure if it's a local issue for me). The sidebar on left goes away for tools section.

Fixed, thanks for spotting -- an odd interaction that I'll look into in Sphinx.

While we are on diataxis, can we get the pretty blocks like https://docs.scipy.org/doc/scipy/ for the homepage? (Doesn't need to happen in this PR)

Yep!

A

[llorracc]

Dominic, Am adding you to the team for reviewing the new documentation -- which sounds like a big improvement. If you can give feedback about how it looks to a HARK newbie and ways it might be improved, that would be great.

…

On Thu, Jul 13, 2023 at 6:06 PM Adam Turner ***@***.***> wrote: The references section behave differently for the tools sections and the models section (Not sure if it's a local issue for me). The sidebar on left goes away for tools section. Fixed, thanks for spotting -- an odd interaction that I'll look into in Sphinx. While we are on diataxis, can we get the pretty blocks like https://docs.scipy.org/doc/scipy/ for the homepage? (Doesn't need to happen in this PR) Yep! A — Reply to this email directly, view it on GitHub <#1302 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAKCK7ZI43VPP3NVNAYUXPLXQBWPTANCNFSM6AAAAAA2IUNDJ4> . You are receiving this because you are subscribed to this thread.Message ID: ***@***.***>

-- - Chris Carroll

[AA-Turner]

@llorracc -- do you have Dominic's GitHub account name to hand please at all? I can then add him to the reviewers group for each PR I open.

Thanks,
Adam

[llorracc]

Dominic, Please send Adam your GitHub ID

On Thu, Jul 13, 2023 at 11:11 PM Adam Turner ***@***.***> wrote: @llorracc <https://github.com/llorracc> -- do you have Dominic's GitHub account name to hand please at all? I can then add him to the reviewers group for each PR I open. Thanks, Adam — Reply to this email directly, view it on GitHub <#1302 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAKCK744LZZN3BKV2SH5DPLXQC2GXANCNFSM6AAAAAA2IUNDJ4> . You are receiving this because you were mentioned.Message ID: ***@***.***>

-- Sent from Gmail Mobile

[alanlujan91]

@DominicWC

[MridulS]

This looks good! Thanks @AA-Turner!