readme: adding quickstart section (#1291)

Co-authored-by: Eric Larson <larson.eric.d@gmail.com>
Co-authored-by: Lucy Liu <jliu176@gmail.com>

README.rst

@@ -39,6 +39,80 @@ Checkout the `documentation <sphinx-gallery.github.io>`_ for introductions on ho
    :width: 80%
    :alt: A demo of a gallery generated by Sphinx-Gallery
 
+Quickstart
+==========
+
+Sphinx-Gallery can be used to generate an example gallery from ``.py`` files,
+for a library,
+as well as a stand-alone web page showcasing examples of a particular
+Python package, module, or class.
+
+Let's get started with a simple example or checkout the
+ `documentation <sphinx-gallery.github.io>`_ for introductions on how
+ to use it and more...
+
+Install via ``pip``
+-------------------
+
+.. installation-begin-content
+
+You can do a direct install via ``pip`` by using:
+
+.. code-block:: bash
+
+    $ pip install sphinx-gallery "sphinx>=4.0" pillow
+
+.. important::
+    Sphinx-Gallery will not manage its dependencies when installing, thus
+    you are required to install them manually. Our minimal dependencies
+    are **Sphinx >= 4** and Pillow, which we use for scaling images.
+
+.. tip::
+    Sphinx-Gallery also has support for scraping images from Matplotlib
+    and Matplotlib-based packages such as Seaborn.
+    We recommend installing system ``optipng`` binaries to reduce
+    the file sizes of the generated PNG files.
+
+.. installation-end-content
+
+Add examples to your docs
+-------------------------
+
+Let's assume simple scenario, you have a Python package with a directory structure like this:
+
+.. code-block::
+
+    ├── doc
+    │   ├── conf.py
+    │   ├── index.rst
+    |   ├── make.bat
+    │   └── Makefile
+    ├── my_python_module
+    │   ├── __init__.py
+    │   └── mod.py
+    └── examples
+        ├── plot_example.py
+        └── README.txt (or .rst)
+
+Enable Sphinx-Gallery by adding the following to your ``doc/conf.py``:
+
+.. code-block:: python
+
+    extensions = [
+        ...
+        'sphinx_gallery.gen_gallery',
+    ]
+
+    # path to the examples scripts
+    sphinx_gallery_conf = {
+        'examples_dirs': '../examples',   # path to your example scripts
+        'gallery_dirs': 'auto_examples',  # path to where to save gallery generated output
+    }
+
+Finally just compile your docs as usual.
+Sphinx-Gallery will generate reST files, adding execution outputs, and save them in ``auto_examples/``.
+Add a link to ``auto_examples/index.rst`` to include the gallery in your documentation.
+
 Who uses Sphinx-Gallery
 =======================
 
@@ -83,30 +157,6 @@ An incomplete list:
 
 .. projects_list_end
 
-Installation
-============
-
-Install via ``pip``
--------------------
-
-.. installation-begin-content
-
-You can do a direct install via ``pip`` by using:
-
-.. code-block:: bash
-
-    $ pip install sphinx-gallery
-
-Sphinx-Gallery will not manage its dependencies when installing, thus
-you are required to install them manually. Our minimal dependencies
-are **Sphinx >= 4** and Pillow, which we use for scaling images.
-
-Sphinx-Gallery has also support for scraping images from packages like
-Matplotlib, Seaborn, and PyVista. We recommend installing system ``optipng``
-binaries to reduce the file sizes of the generated PNG files.
-
-.. installation-end-content
-
 Contributing
 ============