NextJS Docs Rewrite

[ZeroIntensity]

trafficstars

Proposal:

I think it's time to say farewell to MkDocs and mkdocs-material. view.py recently tried writing its own theme for MkDocs, but the result wasn't what I wanted, and so I rolled the docs over to mkdocs-material instead.

The plan now is to use NextJS and MDX for documentation. The most challenging part of this migration (apart from actually writing the docs) is going to be dealing with mkdocstrings generation. I somehow need to figure out how to transfer the generated markdown from mkdocstrings to the TypeScript code. If all fails, view.py will have to abandon mkdocstrings, and write the API reference from scratch (which won't be pretty.)

This will also switch the build system from Netlify to Vercel, but that should be fine.

[pravintargaryen]

Hi @ZeroIntensity, please elaborate on this

The most challenging part of this migration (apart from actually writing the docs) is going to be dealing with mkdocstrings generation. I somehow need to figure out how to transfer the generated markdown from mkdocstrings to the TypeScript code.

[ZeroIntensity]

Mkdocstrings is used to generate our API reference page, but since the plan here is to completely move away from mkdocs, we can't use it anymore. We'll probably have to write our own library/plugin for generating MDX or HTML from our API. (As a side note, I've taken a break from view.py to work on CPython.)

[pravintargaryen]

Thanks for the update! Writing a custom library/plugin for generating MDX or HTML from the API sounds like a solid approach, especially if it gives more control over the output format and styling.

Also, it's exciting to hear about your work on CPython!

P.S : I'm getting into view.py to explore how deep the rabbit hole goes

[ZeroIntensity]

I already have some work on the next-docs branch, but I don't think I got around to generating the API reference. We could also use griffe2md, but then we lose control over the styling.

[pravintargaryen]

Thanks! I’ll take a look at the next-docs branch to see where things stand. Using griffe2md could be a quicker solution, but I get how losing control over styling can be a dealbreaker.

I'll be exploring other options as well and keep you posted.

We also might look into it depending on the results

If all fails, view.py will have to abandon mkdocstrings, and write the API reference from scratch (which won't be pretty.)