DOC Updates contributing.rst with doc build instructions (scikit-lear…

…n#10272)

doc/README.md

@@ -1,42 +1,6 @@
 # Documentation for scikit-learn
 
 This directory contains the full manual and web site as displayed at
-http://scikit-learn.org.
-
-## Building manually
-
-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
-
-Or, if you'd rather not build the example gallery:
-
-    make html-noplot
-
-That should create all the doc in directory `_build/html`
-
-To build the PDF manual, run
-
-    make latexpdf
-
-Make sure you first have the correct version of scikit-learn
-
-## Hosting and automatic builds
-
-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.)
+http://scikit-learn.org. See
+http://scikit-learn.org/dev/developers/contributing.html#documentation for
+detailed information about the documentation. 

doc/developers/contributing.rst

@@ -231,7 +231,7 @@ rules before submitting a pull request:
       automatically be closed by GitHub. If your pull request is simply
       related to some other issues/PRs, create a link to them without using
       the keywords (e.g., ``See also #1234``).
-    
+
     * All public methods should have informative docstrings with sample
       usage presented as doctests when appropriate.
 
@@ -428,19 +428,37 @@ Documentation
 
 We are glad to accept any sort of documentation: function docstrings,
 reStructuredText documents (like this one), tutorials, etc. reStructuredText
-documents live in the source code repository under the doc/ directory.
-
+documents live in the source code repository under the ``doc/`` directory.
 You can edit the documentation using any text editor, and then generate the
-HTML output by typing ``make html`` from the doc/ directory. Alternatively,
-``make html-noplot`` can be used to quickly generate the documentation without
-the example gallery. The resulting HTML files will be placed in _build/html/
-and are viewable in a web browser. See the README file in the doc/ directory
-for more information.
-
-For building the documentation, you will need `sphinx
-<http://www.sphinx-doc.org/en/stable/>`_,
-`matplotlib <http://matplotlib.org>`_ and
-`pillow <http://pillow.readthedocs.io/en/latest/>`_.
+HTML output by building the documentation website.
+
+**Building the documentation**
+
+Building the documentation requires the ``sphinx``, ``sphinx-gallery``,
+``numpydoc``, ``matplotlib``, and ``Pillow`` packages::
+
+    pip install sphinx sphinx-gallery numpydoc matplotlib Pillow
+
+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
+
+Or, if you'd rather quickly generate the documentation without the example
+gallery::
+
+    make html-noplot
+
+That should create all the documentation in the ``_build/html/stable`` directory.
+
+To build the PDF manual, run::
+
+    make latexpdf
 
 **When you are writing documentation**, it is important to keep a good
 compromise between mathematical and algorithmic details, and give

doc/developers/maintainer.rst

@@ -8,12 +8,12 @@ For more information see https://github.com/scikit-learn/scikit-learn/wiki/How-t
 
 1. Update docs:
 
-    - edit the doc/whats_new.rst file to add release title and commit
-      statistics. You can retrieve commit statistics with::
+   - Edit the doc/whats_new.rst file to add release title and commit
+     statistics. You can retrieve commit statistics with::
 
         $ git shortlog -ns 0.998..
 
-    - edit the doc/index.rst to change the 'News' entry of the front page.
+   - Edit the doc/index.rst to change the 'News' entry of the front page.
 
 2. Update the version number in sklearn/__init__.py, the __version__
    variable
@@ -38,7 +38,6 @@ For more information see https://github.com/scikit-learn/scikit-learn/wiki/How-t
 5. Push the documentation to the website. Circle CI should do this
    automatically for master and <N>.<N>.X branches.
 
-
 6. Build binaries using dedicated CI servers by updating the git submodule
    reference to the new scikit-learn tag of the release at:
 
@@ -54,6 +53,16 @@ For more information see https://github.com/scikit-learn/scikit-learn/wiki/How-t
 
 7. FOR FINAL RELEASE: Update the release date in What's New
 
+The scikit-learn.org web site
+-----------------------------
+
+The scikit-learn web site (http://scikit-learn.org) 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 the documentation
+automatically.
+
 Travis Cron jobs
 ----------------