[SIP-47] modernize/facelift superset.apache.org

Motivation

Our current documentation at superset.apache.org has a certain number of issues:

1. look/feel is dated
2. RST/Sphinx/ old templates is a fading/dying standard, markdown seems much more popular
3. can’t add rich/dynamic content - it’s super static
4. Content is a bit of a patchwork, needs review/restructure/rewrite

This SIP looks to address 1,2 and 3, and hope that those provide a foundation to docs that people want to contribute to and improve, content-wise.

Proposed Change

Migrating the current website from/to:

• framework: moving from Sphinx to Gatsby (45k stars) / DocZ (19k stars)
• language: moving from RST to markdown
• hosting: moving from readthedocs to GitHub Pages (or similar)

Gatsby would allow us to build a fast and modern static site. It provides a lot of flexibility / extensibility if we wanted to do more complex things like exposing a community blog.

DocZ is markdown + jsx, allowing us to integrate arbitrarily complex things in our docs, including things like live examples (embedded Superset components) or anything really.

Markdown is a more common markup language for docs. Most people know it or can learn it very quickly, including tech writers, it’s becoming fairly standard.

New or Changed Public Interfaces

N/A

New dependencies

Gatsby / Docz and whatever plugins and things we need there

Migration Plan and Compatibility

Would keep everything under the current main repo under docs/

• individual RST files need to be converted to MD, this can be mostly automated https://cloudconvert.com/rst-to-md , we probably need to do some manual work
• build a new Gatsby / DocZ site, with a good looking theme, maybe with AntD + gatsby-plugin-antd

Rejected Alternatives

• Improving / theming readthedocs
• Other static sites / documentation builder

[mistercrunch]

Looking at the Airflow docs http://airflow.apache.org (rewrite was sponsored by Google I believe), I’m inspired that we could do more eventually, building a blog, events page (gatsby has a meetup.com plugin for instance), maybe even things like a dynamic FAQ or some integrations with StackOverflow, Github and whatnot. Unclear how much flexibility is offered on the Docusaurus to do that.

The beauty of the markdown-based solution is that it becomes very much the meat and it seems like changing the shell should be easy.

---

I terms of effort, we’re interested in sponsoring / leading this at Preset. We’re not looking for any sort of editorial control on it, just to have a rich, beautiful and modern community website.

[mistercrunch]

In short:

• Docusaurus is more fitted to a simpler use case
• Gatsby is more extensible / flexible

Key immediate things:

• Docusaurus has better support for versioning, DocZ is working on it, there are ways to do it with DocZ, it’s more involved though
• Docusaurus has a i18n “coming soon” thing that could be interesting to us