[docs] update the tutorial

[mistercrunch]

The tutorial here: http://airbnb.io/superset/tutorial.html is out of date, we should re-do the screenshots and review the flow.

[QiXuanWang]

Yes, some of them are wrong actually.
For example, create new table won't work at all. And so far I can't figure it out yet.

[dylburger]

@mistercrunch I'd love to hack on this, if you're willing to let me take a stab and get feedback from you and others here.

I've started mocking up a new tutorial in a Google Doc, here. Working on this more today and throughout the week and will let you know when I have a good first draft.

[dylburger]

I've finished a first draft of the tutorial here. Please ignore everything after the Advanced Table Configuration header. That's the start of content to show users how to create custom formatting, metrics, dimensions, etc. that I'd like to add (let me know if you have any specific thoughts on items worth adding).

@mistercrunch let me know if you have any feedback, and please share with anyone who you think should review. I think it covers the lowest common denominator user, who's brand new to the concepts and language around Superset.

If this looks OK, I can start mapping this to the docs in the actual source.

[QiXuanWang]

I had a quick look and it actually looks like the screen I saw from firefox which makes me/new user more comfortable that they are doing things right:)

I likes the clarification of slice=query concept which I guessed but not sure until read about it. This slides do help new user to understand what problem superset is about to solve.

One thing I still have puzzle is postgresql URI. I remember I used sqlite3 somehow, considering I have no idea about what superset was at that time. Does this mean new example data is stored in postgresql? Or it's OK to use postgresql/sqlite3 here provided you modify config.py correspondingly? I do modify that to use sqlite3 since I just want a quick try when I have no postgresql installed.

[dylburger]

Yes, I can understand how the use of PostgreSQL for the example is confusing. I believe the example data that comes pre-loaded with Superset (e.g. the birth name data) is still stored in SQLite. Since part of the goal of the tutorial is to show administrators how to connect to new data sources, I had to use a different database.

Here, I didn't make any changes to any of the Python code - I just formatted a SQLAlchemy connection URI tied to a database I installed on my local machine.

Since SQLLite is supported by SQLAlchemy, if you've already installed that, you can connect Superset to data there. See the connection docs for SQLLite.

It's also clear that we can separate the database connection portion of the tutorial (for administrators) from the exploration / dashboard portion (for normal users). For the exploration section, it might make sense to use the birth name data - since that comes pre-installed - so that users can follow along. I can make that change.

Does that help?

[mistercrunch]

This is awesome! Would love to bring that to replace what is currently here: http://airbnb.io/superset/tutorial.html . The docs are written in rst format which isn't the greatest but is pretty easy to pick up. It's pretty much just a matter of editing the rst files and running the python setup.py build_sphinx command from the root of the repo. You can then point you browser to the folder where sphinx puts the static html files. You may have to run pip install -r dev-reqs.txt prior to that to install some package dependencies.

Would love if you or someone else could translate that doc to rst and send PR.

Here's the rst behind the current tutorial:
https://github.com/airbnb/superset/blob/master/docs/tutorial.rst

[dylburger]

@mistercrunch awesome, I can definitely submit a PR. Thanks!

[dylburger]

@mistercrunch the Sphinx build is working well - getting the tutorial converted to rst without many problems. Thanks for the dev advice.

One question: the current tutorial references images in docs/_static/, e.g.

.. image:: _static/img/tutorial/db_plus.png

but the images themselves aren't committed to the repo, which makes sense. When I commit the PR, I'm just wondering how I actually get y'all the new images so that the docs build correctly?

[dylburger]

@mistercrunch sorry to bug, but the tutorial is finished, just want to figure out how to handle the images (see question above) before I push the PR.

[dylburger]

@mistercrunch apologies for bugging again, just wanted to check in to ask one question before I push my PR. If there's anyone else on the team who I should work with, definitely feel free to add them here so I'm not always bugging you!

One question: the current tutorial references images in docs/_static/, e.g.

.. image:: _static/img/tutorial/db_plus.png

but the images themselves aren't committed to the repo, which makes sense. When I commit the PR, I'm just wondering how I actually get y'all the new images so that the docs build correctly?

[dylburger]

@xrmx I noticed you've made a few commits to the Superset docs. I had one question about the rst files, if you knew how this is managed:

The current tutorial references images in docs/_static/, e.g.

.. image:: _static/img/tutorial/db_plus.png

but the images themselves aren't committed to the repo, which makes sense. When I commit the PR, I'm just wondering how I actually get y'all the new images so that the docs build correctly on airbnb.io?

[xrmx]

@dylburger find suggests they are inside superset/assets/images/tutorial

[dylburger]

@xrmx awesome, I also see how the docs/build.sh script seems to copy any images in that assets dir to the _static/img directory. I'm assuming this is run to actually generate the docs once committed?

I really appreciate the help! Pushing the PR now.

[QiXuanWang]

Some more update on possible "Advanced tutorial".
I found that the only explanation on "Series", "Entity", "Metric" etc was the live hint of "mouse-over". That would be cool if it could be explained somewhere connecting to the examples shipped.
And it's also beneficial to add indicator of what's necessary and what's not.
I was playing around with "Bubble" chart type with my own data. And I don't have Series/Entity recognized so it reports "Pick a metric for x,y and size" error which is very hard to understand since there is no "Metric" field at all.

[QiXuanWang]

Had one more comment on Bubble Viz Type, but maybe applicable to other viz types:

1. You need to run "pd.to_datetime()" to convert datetime to SQL recognized datetime format.
2. In pd.to_sql(), dtype parameter is necessary for at least 3 parameter:
   a. DateTime() for your datetime parameter.
   b. Series parameter for bubble chart must be String() type
   c. Entity parameter for bubble chart must be String() type
   Otherwise, none of above could recognize correctly in sqlab somehow. Maybe it's common sense but just record here in case it's not.