Add modified core docs to website, Partially flatten navbar

[Kajmany]

Description

Ref #211 because I saw a maintainer was O.K with adding core to docs, but I also did some stuff you might not want along with that.

• Navbar flattening: When I first opened the docs I didn't realize there was more than two sections because we start inside of a nested menu rather than the root. I noticed the docs site for the docs site does the same thing, but I found it really confusing. I also thought the nesting in Tutorials and Release Notes were unnecessary. The navbar takes an awkward and laggy double-click to expand for me, so I think it is more convenient now.
• Adding core: Adding a blank __init__.py to core made this doable with an easy kludge inside the reference script, but I don't know if this causes problems elsewhere. I think this SO link might apply to why I had trouble getting mkdocstrings to load the modules -- it's purposeful by griffe? I'm not great with Python or Python packaging, so hopefully you know if it's a bad idea making core not be an implicit namespace package anymore(?)
• Fixing griffe warnings: The vast majority of these were type declarations that were redundant or had less information than the type hints in the functions themselves. A couple spots look like there was a refactor and the doc strings lagged behind. They don't look fantastic still: the Sphinx-style cross-references seem broken and some things like empty :rtype seem to make empty tables, but I hope it's good enough for now.

Tested locally with

rm -rf ./docs/reference/
uv run python scripts/mkdocs_generate_reference.py
uv run python scripts/mkdocs_generate_release_notes.py
uv run mkdocs serve

because it seemed like a lot of effort to replicate the GH-pages on a fork.

Also FYI that this doc generator is apparently being killed maintenance moded in favor of an open-source but commercial project. I would not be in a rush to migrate if I were you, though 🤷

Pre-merge Checklist

• I have described my change in the section above.
• I have ran the ./scripts/format.sh and ./scripts/lint.sh scripts. My code is properly formatted and has no linting errors.
• I have ran uv run pytest and ensured all tests pass no more fail than when I started.
• I have added my change to CHANGELOG.md under the [Unreleased] section.

[github-actions]

This pull request has been marked stale because it has been open for 30 days with no activity. If there is no activity within 7 days, it will be automatically closed.

[stephanlensky]

Hi @Kajmany, so sorry I missed this pull request for so long. Thank you for the submission, I tested locally and the core reference looks great. I don't think we should flatten the navigation though, would you mind changing it back before we merge?

The navbar takes an awkward and laggy double-click to expand for me, so I think it is more convenient now.

I'm not sure what you mean about this - on my machine (Linux/Chrome) it defaults to expanded and is just one click to toggle. Is this from a phone?

Anyways, I'd rather follow the recommended patterns for organizing content from the material-mkdocs library, hopefully if there are any issues with the CSS they can be fixed upstream.

Adding core: Adding a blank __init__.py to core made this doable with an easy kludge inside the reference script, but I don't know if this causes problems elsewhere.

I think that's totally fine, actually this package should have had it already. The fact that it was missing is probably just an oversight.

Fixing griffe warnings: The vast majority of these were type declarations that were redundant or had less information than the type hints in the functions themselves.

Thank you, this is great. I added the native type annotations after the fact, but did not go back and update the docstrings. They can probably all be removed if griffe is able to get the same information from the type annotations directly.

Also FYI that this doc generator is apparently being squidfunk/mkdocs-material#8523 in favor of an open-source but commercial project.

That's a shame, I heard about the new project but didn't know they would no longer maintain this one. I think the theme of Zensical is nicer and more modern looking, but I haven't heard much about their monetization model.

[Kajmany]

Thanks for your reply! I do not expect any SLA doing a cold PR on a project 😉

I'm not sure what you mean about this - on my machine (Linux/Chrome) it defaults to expanded and is just one click to toggle. Is this from a phone?

Anyways, I'd rather follow the recommended patterns for organizing content from the material-mkdocs library, hopefully if there are any issues with the CSS they can be fixed upstream.

I recorded a short video on KDE/Chrome/Linux of what I mean: ihatehamburgermenus.webm. I also just noticed that the hamburger menu is only forced when the window width isn't very high -- the other view works fine.

Ideally it would be fixed upstream, but I wouldn't expect them to now. It was mostly a minor annoyance "while I'm at it" change that only mitigates a bit, and I don't have any qualms reverting.

Thank you, this is great. I added the native type annotations after the fact, but did not go back and update the docstrings. They can probably all be removed if griffe is able to get the same information from the type annotations directly.

Looking back, there's quite a few blank param tags -- I think they're only needed if you want to describe a parameter now that there's type annotations. TBH I don't really have time to make another pass for them right now (and I don't think they cause any real harm), but I won't be offended if you want to modify my branch for that.

Also FYI that this doc generator is apparently being squidfunk/mkdocs-material#8523 in favor of an open-source but commercial project.

That's a shame, I heard about the new project but didn't know they would no longer maintain this one. I think the theme of Zensical is nicer and more modern looking, but I haven't heard much about their monetization model.

I really love the design, stack, etc - but I always worry what projects like that will do when they run low on funds. Hopefully it goes well for them.

[Kajmany]

@stephanlensky I rebased out the flattening. Needed a second shot because I forgot to update the changelog.

[stephanlensky]

I recorded a short video on KDE/Chrome/Linux of what I mean: ihatehamburgermenus.webm. I also just noticed that the hamburger menu is only forced when the window width isn't very high -- the other view works fine.

That's indeed quite annoying. I do think it's important for the organization though, especially with the higher window width view, so thank you for reverting.

Looking back, there's quite a few blank param tags -- I think they're only needed if you want to describe a parameter now that there's type annotations. TBH I don't really have time to make another pass for them right now (and I don't think they cause any real harm), but I won't be offended if you want to modify my branch for that.

No problem, something is better than nothing. I haven't had as much time to work on this project lately, but we can leave it in case someone else wants to come take another pass.

[stephanlensky]

This looks great, thanks!

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!