From a40e49009f1a8c589622a14ea0b95a872faadc29 Mon Sep 17 00:00:00 2001
From: Maoz Gelbart <13831112+MaozGelbart@users.noreply.github.com>
Date: Mon, 13 Jul 2020 09:13:05 +0300
Subject: [PATCH] Elaborate on how to build the docs

---
 README.md     |  5 ++++-
 doc/README.md | 10 ++++++++++
 2 files changed, 14 insertions(+), 1 deletion(-)
 create mode 100644 doc/README.md

diff --git a/README.md b/README.md
index a33f6728d2..cb4118872f 100644
--- a/README.md
+++ b/README.md
@@ -71,10 +71,13 @@ You may instead want to use the development version from Github:
 Testing
 -------
 
-To test the code, run `make test` in the source directory. This will exercise both the unit tests and docstring examples (using `pytest`).
+Testing seaborn requires installing additional packages listed in `ci/utils.txt`.
+
+To test the code, run `make test` in the source directory. This will exercise both the unit tests and docstring examples (using [pytest](https://docs.pytest.org/)).
 
 The doctests require a network connection (unless all example datasets are cached), but the unit tests can be run offline with `make unittests`. Run `make coverage` to generate a test coverage report and `make lint` to check code style consistency.
 
+To build seaborn's documentation, please refer to [how to build the docs?](doc/README.md).
  
 Development
 -----------
diff --git a/doc/README.md b/doc/README.md
new file mode 100644
index 0000000000..1b45b8b31e
--- /dev/null
+++ b/doc/README.md
@@ -0,0 +1,10 @@
+How to build the docs?
+======================
+
+Building the docs requires installing the dependencies listed in `requirements.txt`.
+
+The building process involves conversion of Jupyter notebooks to `rst` files. To facilitate this you need to set `NB_KERNEL` environment variable to the desired python kernel (e.g. `export NB_KERNEL="python3"`). To get a list of python kernels available, run `jupyter kernelspec list`.
+
+After you're set, from the `doc` directory run `make notebooks html` to convert all notebooks, build all gallery examples and the documentation iteslf. The designated output folder is `_build/html`. 
+
+Run `make clean` to delete a built documentation.
\ No newline at end of file