[MRG + 1] DOC Update doc/README.md
# 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.)
