feat: Improve docs: UI, Features, Extensibility

[versecafe]

This is just a proposal to move over to Nextra for documentation as full MDX gives a lot more flexibility in terms of embedding demos, custom components, and more in the future but also it provides a far nicer experience for navigating around the docs along with a cleaner overall UI.

UI Comparrison

Improved ease of editing

Allow community discovered issues to be patched and fixed in a minute or two with a quick PR by linking directly to source files

Subpage Linking

Support for linking to page sections like /guide/cookies/response_cookies#remove-a-client-side-cookie inside of longer pages when sharing or searching for documentation.

Maintenance Improvements

• Complete removal of doc_examples folder and it's sprawl of dozens of *.snap files per section
• Direct control over custom components rather than reliance on Material for MkDocs.

Also the side bar is much nicer for finding things, Material MkDocs is kind of a pain to navigate around you can't see upper or lower folder levels when on medium width screens or doing split tabs

Other note, I'm completely willing to port this over I just decided to try out a simple port since navigating around the docs to learn more about the framework was frustratingly difficult while trying to have anything else open

[LukeMathWalker]

Thank you for the suggestion! Sub-header linking can definitely be achieved in Material for MkDocs, it just needs to be configured.
We can also work on the sidebar/viewport issues by customizing the theme in Material for MkDocs.

I don't quite see the point in switching to an entirely new doc generation framework for a few UI improvements. I'd rather work within what's already here. There is also another angle, maintenance: I'm much more familiar and capable of hacking on MkDocs (being written in Python) than something written in JS on top of NextJS.

Complete removal of doc_examples folder and it's sprawl of dozens of *.snap files per section

Those would be there regardless of the UI framework being chosen and they form a very robust system to have maintainable and continuously tested examples.

[versecafe]

I don't quite see the point in switching to an entirely new doc generation framework for a few UI improvements. I'd rather work within what's already here. There is also another angle, maintenance: I'm much more familiar and capable of hacking on MkDocs (being written in Python) than something written in JS on top of NextJS.

One of the biggest benefits is the ability to add features like this where just for the demo below it hits the localhost:8000/api/ping endpoint and then loads in and renders the response directly inline through the guides, this is just one of the simplest demos, but it allows you to configure mocks to test things as users go through guides and easily see the results

https://github.com/LukeMathWalker/pavex/assets/147033096/6d25bfeb-8327-42e6-b311-c041413c0d4f

I did just mock this up using a axum server on 8000 since I don't have access to Pavex but it shows the point