Improve docs (streamlit#1075)

* Improve docs.

* Apostrophes

docs/cli.md

@@ -25,9 +25,9 @@ Runs your app. At any time you can kill the server with **Ctrl+c**.
 
 ```eval_rst
 .. note::
-  When passing your script some custom arguments, **they must be passed after a
-  "--"** (double dash). Otherwise the arguments get interpreted as arguments to
-  Streamlit itself.
+  When passing your script some custom arguments, **they must be passed after
+  two dashes. Otherwise the arguments get interpreted as arguments to Streamlit
+  itself.
 ```
 
 You can also pass in config options to `streamlit run`. These allow you to do

docs/getting_started.md

@@ -1,12 +1,12 @@
 # Get started
 
 The easiest way to learn how to use Streamlit is to try things out yourself. As
-you read through this guide, test each method. As long as your app is
-running, every time you add a new element to your script and save, Streamlit's
-UI will ask if you'd like to rerun the app and view the changes. This allows
-you to work in a fast interactive loop: you write some code, save it, review
-the output, write some more, and so on, until you're happy with the results.
-The goal is to use Streamlit to create an interactive app for your data or model
+you read through this guide, test each method. As long as your app is running,
+every time you add a new element to your script and save, Streamlit's UI will
+ask if you'd like to rerun the app and view the changes. This allows you to
+work in a fast interactive loop: you write some code, save it, review the
+output, write some more, and so on, until you're happy with the results. The
+goal is to use Streamlit to create an interactive app for your data or model
 and along the way to use Streamlit to review, debug, perfect, and share your
 code.
 
@@ -39,9 +39,10 @@ these commands in a virtual environment. This ensures that the dependencies
 pulled in for Streamlit don't impact any other Python projects
 you're working on.
 
-- [virtualenv](https://virtualenv.pypa.io/en/latest/)
-- [venv](https://docs.python.org/3/library/venv.html)
 - [pipenv](https://docs.pipenv.org/en/latest/)
+- [venv](https://docs.python.org/3/library/venv.html)
+- [virtualenv](https://virtualenv.pypa.io/en/latest/)
+- [conda](https://www.anaconda.com/distribution/)
 
 ## Install Streamlit
 

docs/index.md

@@ -33,61 +33,77 @@
 # Welcome to Streamlit
 
 Streamlit is an open-source Python library that makes it easy to build
-beautiful apps for machine learning.
+beautiful custom web-apps for machine learning and data science.
 
-Install Streamlit, import it, write some code, and run your script. Streamlit
-watches for changes on each save and updates automatically, visualizing your
-output while you're coding. Code runs from top to bottom, always from a clean
-state, and with no need for callbacks. It's a simple and powerful app model
-that lets you build rich UIs incredibly quickly. To learn more about how
-Streamlit works, see [Main concepts](main_concepts.md).
+To use it, just `pip install streamlit`, then import it, write a couple lines
+of code, and run your script with `streamlit run [filename]`. Streamlit watches
+for changes on each save and updates the app live while you're coding. Code
+runs from top to bottom, always from a clean state, and with no need for
+callbacks. It's a simple and powerful app model that lets you build rich UIs
+incredibly quickly. To learn more about how Streamlit works, see [Main
+concepts](main_concepts.md).
+
+You may also want to check out [this four-part
+video](https://www.youtube.com/watch?v=R2nr1uZ8ffc&list=PLgkF0qak9G49QlteBtxUIPapT8TzfPuB8)
+recorded at our PyData talk on December 2019. In it we describe the motivation
+behind Streamlit, then go over how to install and create apps with it.
+
+## Install Streamlit
 
 ```eval_rst
 .. raw:: html
 
   <iframe
     width="560"
     height="315"
-    src="https://www.youtube.com/embed/B2iAodr0fOo"
+    src="https://www.youtube.com/embed/sxLNCDnqyFc"
     style="margin: 0 0 2rem 0;"
     frameborder="0"
     allow="accelerometer; autoplay; encrypted-media; gyroscope; picture-in-picture"
     allowfullscreen></iframe>
 ```
 
-## Install Streamlit
-
-Follow these steps and you'll have a sample app running in less than 5 minutes.
+Follow these steps and to get a sample app running in less than 5 minutes.
 
-1. Make sure that you have [Python 2.7.0
-   / Python 3.6.0](https://www.python.org/downloads/) or greater installed.
-2. Install Streamlit using [PIP](https://pip.pypa.io/en/stable/installing/):
+1. Make sure that you have [Python 2.7.0 / Python 3.6.0](https://www.python.org/downloads/) or greater installed.
+1. Install Streamlit using [PIP](https://pip.pypa.io/en/stable/installing/):
    ```bash
    $ pip install streamlit
    ```
-3. Run the hello world app:
-
+1. Run the hello world app:
    ```bash
    $ streamlit hello
    ```
-
-4. That's it! In the next few seconds the sample app will open in a new tab in
+1. That's it! In the next few seconds the sample app will open in a new tab in
    your default browser.
 
 ## Get started
 
-The easiest way to learn how to use Streamlit is to try it out. Use our [get
-started guide](getting_started.md) to kick the tires, and learn the basics of
-building an app.
+The easiest way to learn how to use Streamlit is to actually try it out. Our
+[get started guide](getting_started.md) walks you through the basics
+of building a Streamlit app.
 
 ## Build your first app
 
-[Create an app](tutorial/create_a_data_explorer_app.md) to explore an Uber
-dataset for pickups in New York City. You'll learn about caching, drawing
-charts, plotting data on a map, and how to use interactive widgets.
+```eval_rst
+.. raw:: html
+
+  <iframe
+    width="560"
+    height="315"
+    src="https://www.youtube.com/embed/VtrFjkSGgKM"
+    style="margin: 0 0 2rem 0;"
+    frameborder="0"
+    allow="accelerometer; autoplay; encrypted-media; gyroscope; picture-in-picture"
+    allowfullscreen></iframe>
+```
+
+[Create an app](tutorial/create_a_data_explorer_app.md) to explore a dataset of
+Uber ride pickups in New York City. You'll learn about caching, drawing charts,
+plotting data on a map, and how to use interactive widgets.
 
 ## Join the community
 
 The quickest way to get help is to reach out on our [community
-forum](https://discuss.streamlit.io/). We'd love to hear your questions, ideas,
-and bugs — please share!
+forum](https://discuss.streamlit.io/). We love to hear our users' questions,
+ideas, and bugs — please share!

docs/main_concepts.md

@@ -1,93 +1,213 @@
 # Main concepts
 
-Working with Streamlit is simple. First you sprinkle a few Streamlit commands into a normal Python script. Then you run the script:
+Working with Streamlit is simple. First you sprinkle a few Streamlit commands
+into a normal Python script, then you run it with `streamlit run`:
 
 ```
-$ streamlit run your_script.py [script args]
+$ streamlit run your_script.py [-- script args]
+```
+
+As soon as you run the script as shown above, a local Streamlit server will
+spin up and your app will open in a new tab your default web browser. The app
+is your canvas, where you'll draw charts, text, widgets, tables, and more.
+
+What gets drawn in the app is up to you. For example
+[`st.text`](apid.html#streamlit.text) writes raw text to your app, and
+[`st.line_chart`](api.html#streamlit.line_chart) draws — you guessed it — a
+line chart. Refer to our [API documentation](api.md) to see all commands that
+are available to you.
+
+```eval_rst
+.. note::
+   When passing your script some custom arguments, they must be passed after
+   two dashes. Otherwise the arguments get interpreted as arguments to
+   Streamlit itself.
 ```
 
 ```eval_rst
 .. tip::
-   Did you know you can also pass a URL to `streamlit run`? This is great when combined with Github Gists. For example:
+   You can also pass a URL to `streamlit run`! This is great when combined with
+   Github Gists. For example:
 
    `$ streamlit run https://raw.githubusercontent.com/streamlit/demo-uber-nyc-pickups/master/app.py`
 ```
 
-As soon as you run the script, a new tab will open in your default browser and connect to a Streamlit server that's automatically launched behind the scenes. In the tab, you'll find your Streamlit app. This is your canvas, where you'll draw charts, text, tables, and more.
+## Development flow
 
-What gets drawn in the app is up to you. For example [`st.text`](apid.html#streamlit.text) writes raw text to your app, and [`st.line_chart`](api.html#streamlit.line_chart) draws — you guessed it — a line chart.
+Every time you want to update your app, just save the source file. When you do
+that, Streamlit detects if there is a change and asks you whether you want to
+rerun your app. Choose "Always rerun" at the top-right of your screen to
+automatically update your app every time you change its source code.
+
+This allows you to work in a fast interactive loop: you type some code, save
+it, try it out live, then type some more code, save it, try it out, and so on
+until you're happy with the results. This tight loop between coding and viewing
+results live is one of that ways Streamlit makes your life easier.
+
+```eval_rst
+.. tip::
+  While developing a Streamlit app, it's recommended to lay out your editor and
+  browser windows side by side, so the code and the app can be seen at the same
+  time. Give it a try!
+```
 
 ## Data flow
 
-Every time you want to update your app, just save your script. The Streamlit server is listening, and will automatically update the report as needed.
+Streamlit's architecture allows you to write apps the same way you write plain
+Python scripts. To unlock this, Streamlit apps have a unique data flow: any
+time something must be updated on the screen, Streamlit just reruns your entire
+Python script from top to bottom.
 
-Behind the scenes, Streamlit re-executes the entire Python script from top to bottom on each save. Then Streamlit does a bunch of computer-science magic to make sure that your report is updated efficiently. If you're wondering how we deal with non-trivial code, the answers is [`@st.cache`](#caching), which we'll cover in the next section.
+This can happen in two situations:
 
-What this all means is that Streamlit allows you to work in a fast interactive loop: you type some code, save, type some more code, save, and on-and-on until you're happy with your app. The idea is to use Streamlit as a place where you can understand your code, debug it, perfect it, and finally share your results.
+- Whenever you modify your app's source code.
 
-## Widgets
+- Whenever a user interacts with widgets in the app. For example, when dragging
+  a slider, entering text in an input box, or clicking a button.
+
+And to make all of this fast and seamless, Streamlit does some heavy lifting
+for you behind the scenes. A big player in this story is the
+[`@st.cache`](#caching) decorator, which allows developers to skip certain
+costly computations when their apps rerun. We'll cover caching later in this
+page.
+
+## Drawing content
 
-When you've got the data or model into the state that you want to explore, you can add in widgets like [`st.slider()`](api.html#streamlit.slider), [`st.button()`](api.html#streamlit.button) or [`st.selectbox()`](api.html#streamlit.selectbox). It's really straightforward - just treat widgets as variables. There are no callbacks in Streamlit! Every interaction simply reruns the script from top-to-bottom. Streamlit assigns each variable an up-to-date value given the app state. This approach leads to really clean code:
+Writing to Streamlit apps is simple. Just call the appropriate API command:
 
 ```python
 import streamlit as st
-x = st.slider('x')
+x = 4
 st.write(x, 'squared is', x * x)
+```
+
+In the example above we used the [`st.write()`](api.html#streamlit.write)
+command. Whenever you want to draw something to the screen
+[`st.write()`](api.html#streamlit.write) is always a good first start! It tries
+to guess the best visual representation for its arguments based on their data
+types, so things like dataframes are drawn as beautiful tables, Matplotlib
+figures are drawn as charts, and so on.
+
+And you can even use [Streamlit magic](api.html#magic) to skip the
+[`st.write()`](api.html#streamlit.write) command altogether:
+
+```python
+import streamlit as st
+x = 4
+x, 'squared is', x * x  # 👈 Magic!
+```
 
+If you want to do something more advanced like changing specific settings,
+drawing animations, or inserting content out of order, check out other
+available Streamlit commands in our [API documentation](api.md) and [Advanced
+Concepts](advanced_concepts.md) pages.
+
+## Widgets
+
+When you've got the data or model into the state that you want to explore, you
+can add in widgets like [`st.slider()`](api.html#streamlit.slider),
+[`st.button()`](api.html#streamlit.button) or
+[`st.selectbox()`](api.html#streamlit.selectbox). It's really straightforward
+— just treat widgets as variables:
+
+```python
+import streamlit as st
+x = st.slider('x')  # 👈 this is a widget
+st.write(x, 'squared is', x * x)
 ```
 
+On first run, the app above should output the text "0 squared is 0". Then
+every time a user interacts with a widget, Streamlit simply reruns your script
+from top to bottom, assigning the current state of the widget to your variable
+in the process.
+
+For example, if the user moves the slider to position `10`, Streamlit will
+rerun the code above and set `x` to `10` accordingly. So now you should see the
+text "10 squared is 100".
+
 ## Sidebar
 
-Streamlit makes it easy to organize your widgets in a left panel sidebar with [`st.sidebar`](api.html#add-widgets-to-sidebar). Each element that's passed to [`st.sidebar`](api.html#add-widgets-to-sidebar) is pinned to the left, allowing users to focus on the content in your app. The only elements that aren't supported are: `st.write` (you
-should use `st.sidebar.markdown()` instead), `st.echo`, and `st.spinner`.
+Streamlit makes it easy to organize your widgets in a left panel sidebar with
+[`st.sidebar`](api.html#add-widgets-to-sidebar). Each element that's passed to
+[`st.sidebar`](api.html#add-widgets-to-sidebar) is pinned to the left, allowing
+users to focus on the content in your app while still having access to UI
+controls.
+
+For example, if you want to add a selectbox and a slider to a sidebar, just
+use `st.sidebar.slider` and `st.siderbar.selectbox` instead of `st.slider` and
+`st.selectbox`:
 
 ```python
 import streamlit as st
 
-# Adds a selectbox to the sidebar
+# Add a selectbox to the sidebar:
 add_selectbox = st.sidebar.selectbox(
     'How would you like to be contacted?',
     ('Email', 'Home phone', 'Mobile phone')
 )
 
-# Adds a slider to the sidebar
+# Add a slider to the sidebar:
 add_slider = st.sidebar.slider(
     'Select a range of values',
     0.0, 100.0, (25.0, 75.0)
 )
 ```
 
+```eval_rst
+.. note::
+  The following Streamlit commands are not currently supported in the sidebar:
+  `st.write` (you should use `st.sidebar.markdown()` instead), `st.echo`, and
+  `st.spinner`.
+```
+
 ## Caching
 
-The Streamlit cache allows your app to stay performant even when loading data from the web, manipulating large datasets, or performing expensive computations.
+The Streamlit cache allows your app to execute quickly even when loading data
+from the web, manipulating large datasets, or performing expensive
+computations.
 
-To use the cache, just wrap functions in the [`@st.cache`](api.html#streamlit.cache) decorator:
+To use the cache, just wrap functions in the
+[`@st.cache`](api.html#streamlit.cache) decorator:
 
 ```python
-@st.cache  # <-- This function will be cached
+@st.cache  # 👈 This function will be cached
 def my_slow_function(arg1, arg2):
     # Do something really slow in here!
     return the_output
 ```
 
-When you mark a function with the [`@st.cache`](api.html#streamlit.cache) decorator, it tells Streamlit that whenever the function is called it needs to check a few things:
+When you mark a function with the [`@st.cache`](api.html#streamlit.cache)
+decorator, it tells Streamlit that whenever the function is called it needs to
+check a few things:
 
 1. The input parameters that you called the function with
-2. The value of any external variable used in the function
-3. The body of the function
-4. The body of any function used inside the cached function
+1. The value of any external variable used in the function
+1. The body of the function
+1. The body of any function used inside the cached function
 
-If this is the first time Streamlit has seen these four components with these exact values and in this exact combination and order, it runs the function and stores the result in a local cache. Then, next time the cached function is called, if none of these components changed, Streamlit will just skip executing the function altogether and, instead, return the output previously stored in the cache.
+If this is the first time Streamlit has seen these four components with these
+exact values and in this exact combination and order, it runs the function and
+stores the result in a local cache. Then, next time the cached function is
+called, if none of these components changed, Streamlit will just skip executing
+the function altogether and, instead, return the output previously stored in
+the cache.
 
-For more information about the Streamlit cache, its configuration parameters, and its limitations, see [Caching](caching.md).
+For more information about the Streamlit cache, its configuration parameters,
+and its limitations, see [Caching](caching.md).
 
 ## App model
 
-Now that you have an idea of what Streamlit is, let's close the loop and review how it works:
-
-1. The entire script is rerun with each save.
-2. Streamlit assigns each variable an up-to-date value based on the current state of the app.
-3. Caching allows Streamlit to skip redundant data fetches and computation.
+Now that you know a little more about all the individual pieces, let's close
+the loop and review how it works together:
+
+1. Streamlit apps are Python scripts that run from top to bottom
+1. Every time a user opens a browser tab pointing to your app, the script is
+   re-executed
+1. As the script executes, Streamlit draws its output live in a browser
+1. Scripts use the Streamlit cache to avoid recomputing expensive functions, so
+   updates happen very fast
+1. Every time a user interacts with a widget, your script is re-executed and
+   the output value of that widget is set to the new value during that run.
 
 ![](media/app_model.png)