switch site to sphinx + myst-parser?

[NickleDave]

Opening an issue here since this will be a big PR, and to avoid me writing lengthy threads about it in Slack.

Since we're pyOpenSci we might want to use Python tools to build the site.

IME converting from any .md-based static site builder to a site built with myst-parser + sphinx is actually fairly painless.
E.g., I converted our site on code review from Hugo to the jupyter book theme built on readthedocs
ResearchCodeReviewCommunity/dev-review#75
https://dev-review.readthedocs.io/en/latest/

Big issue would be the theme we have.
AFAICT it's minimal-mistakes with some custom css?
I don't know how much of the theme-ing happens in Ruby v. html + css -- i.e. if we could just vendor the html + css to make an initial transition then it would be easy to test out with a PR.

[lwasser]

Thanks @NickleDave ... in terms of web dev, do you know what sphinx would offer us that we can't do with other known web platforms? i know @choldgraf website is sphinx. but we will want to do more advanced web dev in the future such as linking to databases and customizing. How hard will that be to do with sphinx? also what if we wantt to add custom JS, etc. will we be fighting the sphinx themes to implement?

i actually don't think we have to build the site with python. i think we should chose the best tool for the job that we need to do! but i'm open to it if it's the best tool and easy to manage / expand. Right now jekylyy on GH pages is limited as it runs in safe mode so i was definitely thinking about a netlify migration when we redo the site! just things to consider!!

yes website is min mistakes and i am customizing it and adding functionality as i go! good eye!

[NickleDave]

👍 good point

You're right that sphinx is mainly meant for technical docs.
I guess I was thinking that we might still end up with a lot of that content, e.g. in package descriptions, and so using sphinx + myst would make it easier for anyone to contribute that content.

I don't have any complete thoughts about web dev although I feel like using a Python framework might make life easier there too. Agree we should use whatever tool is fit to task, just trying to think about maintainability + ease of contributions. I mean there's a reason django is so popular 🙂

[lwasser]

Totally!! these are all excellent points! and it would be cool to automate things with Python... much easier for me and us all. But what i don't know is if that means we need to use sphinx or some other python framework to do what we need!

i do like the idea of keeping the site in a markdown or RST or text based / yaml format for ease of content update.

let's keep this convo going!

[NickleDave]

Closing this for now just to whittle down issues