Use JupyterBook and Sphinx instead of mkdocs

[sequoiap]

Is your feature request related to a problem? Please describe.
I don't like mkdocs, it's not as user friendly or organized. While the website theme looks nice, usability suffers in my opinion. I know a lot of famous projects use it (Pydantic, FastAPI, etc.) but I literally dread going to their docs. I have to look through everything, because it's all nested in prose, which is the main selling point of mkdocs. It takes so much longer to read and find what I want. Sphinx is great, API generation in Sphinx is great, and it's a heavily-developed and well-proven library. There are too many tradeoffs with mkdocs. And the API documentation is ugly and hard to read.

Describe the solution you'd like
Switch the docs to JupyterBook. Write them all in markdown.

I strongly believe in The Grand Unifying Theory of Documentation. That means the docs have tutorials, how-to guides, explanations, and an easy to use reference. Mkdocs excels at tutorials; it's great for writing prose. That's only useful as a beginner; once you're coming back to the docs to actually be productive, you want a good API. And mkdocs just really doesn't have a good API experience. Presently, when viewing kfactory's API docs, I have to do a whole bunch of sideways scrolling to view typehints, function signatures, etc.

Describe alternatives you've considered
JupyterBook is the alternative to mkdocs 😉

Additional context
gdsfactory docs were jupyterbook. Super easy to maintain. Built for converting notebooks to webpages. Easy to download/run notebooks elsewhere. This kind of stuff is not available in mkdocs.

[sequoiap]

I'd also be happy to create the docs/make a pull request that switches them over, if we're willing to switch.

[joamatab]

I also like this project from the same group as jupyter-book

https://myst-tools.org/docs/mystjs

[sequoiap]

Ooh, I've never seen that one before. I agree, it looks even better than JupyterBook. Best part about it is the navigation on the left not changing position when you go to different pages (like scrolling all the way back to the top).

[sequoiap]

Although @joamatab I'm not seeing a search feature, which is going to be essential for a documentation site...

[joamatab]

search is not implemented yet

jupyter-book/mystmd#100

[sebastian-goeldi]

Could you elaborats what you mean by sideways scrolling? There's a lot of tweaking I can do on the navigation. And for sure it's far from perfect.

Overall I totally disagree with the statement that sphinx is easier to maintain. I guess for the one off build of the docs that might be true. To get the apidoc to work was a nightmare in sphinx whereas griffe gives way better output and was very fast to set up. mkdocs and mkdocstrings seem to have at least as much support and development as their sphinx equivalents, so I don't see that as a big issue at all.