[MRG + 1] DOC Update doc/README.md (scikit-learn#10225)

Author: jnothman

doc/README.md

@@ -1,12 +1,21 @@
 # Documentation for scikit-learn
 
-This section contains the full manual and web page as displayed in
+This directory contains the full manual and web site as displayed at
 http://scikit-learn.org.
-Building the website requires the sphinx and sphinx-gallery packages:
 
-    pip install sphinx sphinx-gallery
+## Building manually
 
-To generate the full web page, including the example gallery (this might take a
+Building the website requires the sphinx, sphinx-gallery and matplotlib
+packages:
+
+    pip install sphinx numpydoc sphinx-gallery matplotlib
+
+It also requires having the version of scikit-learn installed that corresponds
+to the documentation, e.g.:
+
+    pip install --editable ..
+
+To generate the full web site, including the example gallery (this might take a
 while):
 
     make html
@@ -15,27 +24,19 @@ Or, if you'd rather not build the example gallery:
 
     make html-noplot
 
-That should create all the doc in directory _build/html
+That should create all the doc in directory `_build/html`
 
 To build the PDF manual, run
 
     make latexpdf
 
-The website is hosted at github and can be updated manually (for releases)
-by pushing to the https://github.com/scikit-learn/scikit-learn.github.io repository.
-
-It's recommended to run OptiPNG, before uploading the website.
-The PNG files generated by Matplotlib tend to be ~20% too big, and they're
-costing us bandwidth. You can run OptiPNG with::
-
-    make optipng
-
-# Development documentation automated build
+Make sure you first have the correct version of scikit-learn
 
-A Rackspace cloud server named 'docbuilder' is continuously building the master branch
-to update the http://scikit-learn.org/dev tree of the website.
+## Hosting and automatic builds
 
-The configuration of this server is managed at:
-
-  https://github.com/scikit-learn/sklearn-docbuilder
+The website is hosted at github, but should rarely be updated manually
+by pushing to the https://github.com/scikit-learn/scikit-learn.github.io repository.
 
+Most updates can be made by pushing to master (for /dev) or a release branch
+like 0.99.X, from which Circle CI builds and uploads documentation. (See the
+Developer Documentation for further details.)