You are viewing a plain text version of this content. The canonical link for it is here.

Posted to notifications@superset.apache.org by GitBox <gi...@apache.org> on 2020/06/17 19:40:25 UTC

[GitHub] [incubator-superset] mistercrunch opened a new issue #10088: [WIP][SIP-?] modernize/facelift superset.apache.org

mistercrunch opened a new issue #10088:
URL: https://github.com/apache/incubator-superset/issues/10088


   # work in progress!
   ## [SIP] modernize/facelift superset.apache.org
   
   ### Motivation
   
   Our current documentation at superset.apache.org has a certain number of issues:
   1. look/feel is dated
   1. RST/Sphinx is a fading/dying standard, markdown seems much more popular
   1. Content is a bit of a patchwork, needs review/restructure/rewrite
   
   This SIP looks to address #1 and #2, 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 / DocZ
   - **language**: moving from RST to markdown
   - **hosting**: moving from readthedocs to GitHub Pages (or similar)
   
   Gatsby would allow us to build a great, 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.
   
   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 automated https://cloudconvert.com/rst-to-md
   * build a new Gatsby / DocZ
   
   
   ### Rejected Alternatives
   - Improving / theming readthedocs
   


----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

For queries about this service, please contact Infrastructure at:
users@infra.apache.org



---------------------------------------------------------------------
To unsubscribe, e-mail: notifications-unsubscribe@superset.apache.org
For additional commands, e-mail: notifications-help@superset.apache.org

[GitHub] [incubator-superset] mistercrunch commented on issue #10088: [SIP-47] modernize/facelift superset.apache.org

Posted by GitBox <gi...@apache.org>.

mistercrunch commented on issue #10088:
URL: https://github.com/apache/incubator-superset/issues/10088#issuecomment-647048991


   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.


----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

For queries about this service, please contact Infrastructure at:
users@infra.apache.org



---------------------------------------------------------------------
To unsubscribe, e-mail: notifications-unsubscribe@superset.apache.org
For additional commands, e-mail: notifications-help@superset.apache.org

[GitHub] [incubator-superset] mik-laj commented on issue #10088: [SIP-47] modernize/facelift superset.apache.org

Posted by GitBox <gi...@apache.org>.

mik-laj commented on issue #10088:
URL: https://github.com/apache/incubator-superset/issues/10088#issuecomment-659384119


   Polidea was doing a similar project.  We use [docsy](https://www.docsy.dev/) for main site and sphinx for documentation. On main website, we have blog, community information and other. Sphinx we use for project documentation  The site is not versioned, but all documentation is. You can choose the Airflow version for which the documentation is to be displayed.
   
   Using the docsy facilitates integration with Sphinx, which uses Jinja as a template engine. We had to use Sphinx and .rst because we generate reference documentation for [the Pytthon API](https://airflow.apache.org/docs/stable/_api/airflow/operators/bash_operator/index.html)
   
   More information: 
   https://airflow.apache.org/blog/announcing-new-website/
   
   I am happy to share my experiences. If you have any questions, I will be happy to answer.


----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

For queries about this service, please contact Infrastructure at:
users@infra.apache.org



---------------------------------------------------------------------
To unsubscribe, e-mail: notifications-unsubscribe@superset.apache.org
For additional commands, e-mail: notifications-help@superset.apache.org

[GitHub] [incubator-superset] rusackas commented on issue #10088: [SIP-47] modernize/facelift superset.apache.org

Posted by GitBox <gi...@apache.org>.

rusackas commented on issue #10088:
URL: https://github.com/apache/incubator-superset/issues/10088#issuecomment-646140235


   Wondering if it's reasonable to use some CSS-in-JS/Emotion in the mix, in order to leverage the @superset-ui theme package here, and "tie the room together" a bit. This would make sense if there's ever an interest in pulling some of the docs/tutorials back into Superset (i.e. inline help buttons popping up tutorial content in a modal).


----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

For queries about this service, please contact Infrastructure at:
users@infra.apache.org



---------------------------------------------------------------------
To unsubscribe, e-mail: notifications-unsubscribe@superset.apache.org
For additional commands, e-mail: notifications-help@superset.apache.org

[GitHub] [incubator-superset] mistercrunch commented on issue #10088: [SIP-47] modernize/facelift superset.apache.org

Posted by GitBox <gi...@apache.org>.

mistercrunch commented on issue #10088:
URL: https://github.com/apache/incubator-superset/issues/10088#issuecomment-647022072


   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


----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

For queries about this service, please contact Infrastructure at:
users@infra.apache.org



---------------------------------------------------------------------
To unsubscribe, e-mail: notifications-unsubscribe@superset.apache.org
For additional commands, e-mail: notifications-help@superset.apache.org

[GitHub] [incubator-superset] mistercrunch edited a comment on issue #10088: [SIP-47] modernize/facelift superset.apache.org

Posted by GitBox <gi...@apache.org>.

mistercrunch edited a comment on issue #10088:
URL: https://github.com/apache/incubator-superset/issues/10088#issuecomment-647021348

@etr2460 Docusaurus looks pretty sweet too, here's their take on how it relates to Gatsby:
https://v2.docusaurus.io/docs/#gatsby

---------

Gatsby is packed with a lot of features, has a rich ecosystem of plugins and is capable of doing everything that Docusaurus does. Naturally, that comes at a cost of a higher learning curve. Gatsby does many things well and is suitable for building many types of websites. On the other hand, Docusaurus tries to do one thing super well - be the best tool for writing and publishing content.

GraphQL is also pretty core to Gatsby, although you don't necessarily need GraphQL to build a Gatsby site. In most cases when building static websites, you won't need the flexibility that GraphQL provides.

Many aspects of Docusaurus 2 were inspired by the best things about Gatsby and it's a great alternative.

---------

----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

---------------------------------------------------------------------
To unsubscribe, e-mail: notifications-unsubscribe@superset.apache.org
For additional commands, e-mail: notifications-help@superset.apache.org

[GitHub] [incubator-superset] mik-laj edited a comment on issue #10088: [SIP-47] modernize/facelift superset.apache.org

Posted by GitBox <gi...@apache.org>.

mik-laj edited a comment on issue #10088:
URL: https://github.com/apache/incubator-superset/issues/10088#issuecomment-659384119

Polidea was doing a similar project. We use [docsy](https://www.docsy.dev/) for main site and sphinx for documentation. On main website, we have blog, community information and other. Sphinx we use for project documentation The site is not versioned, but all documentation is. You can choose the version of Airflow. We also have latest version from master branch available at https://airflow.readthedocs.io/en/latest/

Using the docsy facilitates integration with Sphinx, which uses Jinja as a template engine. We had to use Sphinx and .rst because we generate reference documentation for [the Pytthon API](https://airflow.apache.org/docs/stable/_api/airflow/operators/bash_operator/index.html)

More information:
https://airflow.apache.org/blog/announcing-new-website/
https://github.com/apache/airflow-site

I am happy to share my experiences. If you have any questions, I will be happy to answer.
My e-mail: kamil.bregula@polidea.com

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

[GitHub] [incubator-superset] kristw commented on issue #10088: [SIP-47] modernize/facelift superset.apache.org

Posted by GitBox <gi...@apache.org>.

kristw commented on issue #10088:
URL: https://github.com/apache/incubator-superset/issues/10088#issuecomment-651408876


   In terms of deployment. Github pages sounds great. Vercal (formerly Zeit) also has native support for Gatsby. 


----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

For queries about this service, please contact Infrastructure at:
users@infra.apache.org



---------------------------------------------------------------------
To unsubscribe, e-mail: notifications-unsubscribe@superset.apache.org
For additional commands, e-mail: notifications-help@superset.apache.org

[GitHub] [incubator-superset] willbarrett commented on issue #10088: [SIP-47] modernize/facelift superset.apache.org

Posted by GitBox <gi...@apache.org>.

willbarrett commented on issue #10088:
URL: https://github.com/apache/incubator-superset/issues/10088#issuecomment-646137041


   +1 :shipit: 


----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

For queries about this service, please contact Infrastructure at:
users@infra.apache.org



---------------------------------------------------------------------
To unsubscribe, e-mail: notifications-unsubscribe@superset.apache.org
For additional commands, e-mail: notifications-help@superset.apache.org

[GitHub] [incubator-superset] etr2460 commented on issue #10088: [SIP-47] modernize/facelift superset.apache.org

Posted by GitBox <gi...@apache.org>.

etr2460 commented on issue #10088:
URL: https://github.com/apache/incubator-superset/issues/10088#issuecomment-645785933


   100% in favor of moving off of RST files and onto something markdown driven. 
   
   I'm curious what other static sites/documentation builders you considered when evaluating options. I'm not super familiar with the space, but I know [Docusaurus](https://docusaurus.io/) is pretty commonly used within the frontend world (Babel, Jest, Redux), also supports adding a blog, and has other features like translated and versioned docs. What tradeoffs did you consider when picking Gatsby + DocZ?


----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

For queries about this service, please contact Infrastructure at:
users@infra.apache.org



---------------------------------------------------------------------
To unsubscribe, e-mail: notifications-unsubscribe@superset.apache.org
For additional commands, e-mail: notifications-help@superset.apache.org

[GitHub] [incubator-superset] issue-label-bot[bot] commented on issue #10088: [WIP][SIP-?] modernize/facelift superset.apache.org

Posted by GitBox <gi...@apache.org>.

issue-label-bot[bot] commented on issue #10088:
URL: https://github.com/apache/incubator-superset/issues/10088#issuecomment-645582146


   Issue Label Bot is not confident enough to auto-label this issue. See [dashboard](https://mlbot.net/data/apache/incubator-superset) for more details.


----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

For queries about this service, please contact Infrastructure at:
users@infra.apache.org



---------------------------------------------------------------------
To unsubscribe, e-mail: notifications-unsubscribe@superset.apache.org
For additional commands, e-mail: notifications-help@superset.apache.org

[GitHub] [incubator-superset] mistercrunch commented on issue #10088: [SIP-47] modernize/facelift superset.apache.org

Posted by GitBox <gi...@apache.org>.

mistercrunch commented on issue #10088:
URL: https://github.com/apache/incubator-superset/issues/10088#issuecomment-646889308


   @etr2460 I have to admit I didn't go super deep in the research. I think Gatsby is super connected to everything and very extensible. DocZ being markdown + jsx/React seemed perfect.
   
   Check out the Gatsby plugin ecosystem
   https://www.gatsbyjs.org/plugins/
   
   DocZ appeared to be top of their doc plugins. I have some experience with both and I think it's hard to top.


----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

For queries about this service, please contact Infrastructure at:
users@infra.apache.org



---------------------------------------------------------------------
To unsubscribe, e-mail: notifications-unsubscribe@superset.apache.org
For additional commands, e-mail: notifications-help@superset.apache.org

[GitHub] [incubator-superset] mik-laj edited a comment on issue #10088: [SIP-47] modernize/facelift superset.apache.org

Posted by GitBox <gi...@apache.org>.

mik-laj edited a comment on issue #10088:
URL: https://github.com/apache/incubator-superset/issues/10088#issuecomment-659384119

More information:
https://airflow.apache.org/blog/announcing-new-website/
https://github.com/apache/airflow-site

I am happy to share my experiences. If you have any questions, I will be happy to answer.

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

[GitHub] [incubator-superset] ktmud commented on issue #10088: [SIP-47] modernize/facelift superset.apache.org

Posted by GitBox <gi...@apache.org>.

ktmud commented on issue #10088:
URL: https://github.com/apache/incubator-superset/issues/10088#issuecomment-649752893


   Another thing to note is should we or how can we integrate autogenerated superset Python module/CLI and Swagger API docs.
   
   DocZ have moved to Gatsby, so it seems any plugin available in Gatsby might also have become available for DocZ.


----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

For queries about this service, please contact Infrastructure at:
users@infra.apache.org



---------------------------------------------------------------------
To unsubscribe, e-mail: notifications-unsubscribe@superset.apache.org
For additional commands, e-mail: notifications-help@superset.apache.org

[GitHub] [incubator-superset] etr2460 commented on issue #10088: [SIP-47] modernize/facelift superset.apache.org

Posted by GitBox <gi...@apache.org>.

etr2460 commented on issue #10088:
URL: https://github.com/apache/incubator-superset/issues/10088#issuecomment-647034831

I think your pros and cons list is accurate. When I was looking at Docusaurus, it seemed like the v1 branch supported versioning and i18n, but not JS in Markdown. v2 has JS in Markdown (which seems like a really good selling point), but hasn't implemented i18n yet.

To me it all comes down to how much effort we want to spend to start up and maintain the new docs. Docusaurus seems easier to spin up and would free up more time to build Superset features vs. documentation. But at the cost of less overall flexibility (an unknown cost for me since it seems to still support all the use cases we want here).

I'd be happy with either option, but might lean slightly towards Docusaurus as it feels like our competitive advantage should live with the product vs. the documentation (thus we should spend more time building the product and less time building docs).

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

[GitHub] [incubator-superset] mistercrunch edited a comment on issue #10088: [SIP-47] modernize/facelift superset.apache.org

Posted by GitBox <gi...@apache.org>.

mistercrunch edited a comment on issue #10088:
URL: https://github.com/apache/incubator-superset/issues/10088#issuecomment-647021348

@etr2460 Docusaurus looks pretty sweet too, here's their take on how it relates to Gatsby:
https://v2.docusaurus.io/docs/#gatsby

---------

Many aspects of Docusaurus 2 were inspired by the best things about Gatsby and it's a great alternative.

---------

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

[GitHub] [incubator-superset] mistercrunch commented on issue #10088: [SIP-47] modernize/facelift superset.apache.org

Posted by GitBox <gi...@apache.org>.

mistercrunch commented on issue #10088:
URL: https://github.com/apache/incubator-superset/issues/10088#issuecomment-647021348

@etr2460 Docusaurus looks pretty sweet too, here's their take on how it relates to Gatsby:
https://v2.docusaurus.io/docs/#gatsby

```
Gatsby is packed with a lot of features, has a rich ecosystem of plugins and is capable of doing everything that Docusaurus does. Naturally, that comes at a cost of a higher learning curve. Gatsby does many things well and is suitable for building many types of websites. On the other hand, Docusaurus tries to do one thing super well - be the best tool for writing and publishing content.

Many aspects of Docusaurus 2 were inspired by the best things about Gatsby and it's a great alternative.
```

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

[GitHub] [incubator-superset] mistercrunch edited a comment on issue #10088: [SIP-47] modernize/facelift superset.apache.org

Posted by GitBox <gi...@apache.org>.

mistercrunch edited a comment on issue #10088:
URL: https://github.com/apache/incubator-superset/issues/10088#issuecomment-647021348

@etr2460 Docusaurus looks pretty sweet too, here's their take on how it relates to Gatsby:
https://v2.docusaurus.io/docs/#gatsby

---------

Many aspects of Docusaurus 2 were inspired by the best things about Gatsby and it's a great alternative.
---------

For queries about this service, please contact Infrastructure at:
users@infra.apache.org