Fix sphinx (networkx#2517)

* Ensure valid rst file

* Edit text

* Update README and package docstring

* Add myself as a contributor

* Update gitwash

* Fix warnings/errors except citations/footnotes

* Remove old note about 3.0 incompatibility

* Remove stale ref to gh-pages

* Create top-level tools directory (standard practice)

* Use sphinx-gallery extension for examples

* Sphinx-gallery generates images for `plot_` examples

* Comply with pep8

* Don't save figures

.gitignore

@@ -15,9 +15,9 @@ doc/build
 *.class
 
 # Generated while building documentation.
-doc/source/static/examples/*
-doc/source/reference/generated/*
-doc/source/examples/*
+doc/source/auto_examples
+doc/source/modules
+doc/source/reference/generated
 
 # Generated when 'python setup_egg.py'
 networkx.egg-info/

README.rst

@@ -14,9 +14,9 @@ NetworkX
 .. image:: https://coveralls.io/repos/networkx/networkx/badge.svg?branch=master
    :target: https://coveralls.io/r/networkx/networkx?branch=master
 
-NetworkX is a Python package for the creation, manipulation, and study of the
-structure, dynamics, and functions of complex networks.
-
+NetworkX is a Python package for the creation, manipulation,
+and study of the structure, dynamics, and functions
+of complex networks.
 
 - **Website (including documentation):** http://networkx.github.io
 - **Mailing list:** https://groups.google.com/forum/#!forum/networkx-discuss
@@ -54,9 +54,10 @@ Bugs
 ----
 
 Please report any bugs that you find `here <https://github.com/networkx/networkx/issues>`_.
-Or, even better, fork the repository on GitHub and create a pull request (PR).
-We welcome all changes, big or small, and we will help you make the PR if you are
-new to `git` (just ask on the issue and/or see `CONTRIBUTE.rst`).
+Or, even better, fork the repository on `GitHub <https://github.com/networkx/networkx>`_
+and create a pull request (PR). We welcome all changes, big or small, and we
+will help you make the PR if you are new to `git` (just ask on the issue and/or
+see `CONTRIBUTE.rst`).
 
 License
 -------

doc/Makefile

@@ -26,19 +26,11 @@ help:
 	@echo "  changes   to make an overview of all changed/added/deprecated items"
 	@echo "  linkcheck to check all external links for integrity"
 	@echo "  doctest   to run all doctests embedded in the documentation (if enabled)"
+	@echo "  gitwash   to update the gitwash documentation"
 
 
 clean:
-	-rm -rf build/* source/reference/generated/* source/examples/* source/static/examples/* doc/source/*.pdf doc/source/*.zip 
-	-rm -rf ../examples/*/*.png
-
-generate: build/generate-stamp
-build/generate-stamp: $(wildcard source/reference/*.rst)
-	mkdir -p build
-	python make_gallery.py 
-	python make_examples_rst.py ../examples source
-	touch build/generate-stamp
-
+	-rm -rf build/* source/auto_examples source/modules source/reference/generated
 
 dist: html
 	test -d build/latex || make latex
@@ -48,33 +40,33 @@ dist: html
 	(cd build/dist && tar czf ../dist.tar.gz .)
 
 
-html: generate
+html:
 	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) build/html
 	@echo
 	@echo "Build finished. The HTML pages are in build/html."
 
-dirhtml: generate
+dirhtml:
 	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) build/dirhtml
 	@echo
 	@echo "Build finished. The HTML pages are in build/dirhtml."
 
-pickle: generate
+pickle:
 	$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) build/pickle
 	@echo
 	@echo "Build finished; now you can process the pickle files."
 
-json: generate
+json:
 	$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) build/json
 	@echo
 	@echo "Build finished; now you can process the JSON files."
 
-htmlhelp: generate
+htmlhelp:
 	$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) build/htmlhelp
 	@echo
 	@echo "Build finished; now you can run HTML Help Workshop with the" \
 	      ".hhp project file in build/htmlhelp."
 
-qthelp: generate
+qthelp:
 	$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) build/qthelp
 	@echo
 	@echo "Build finished; now you can run "qcollectiongenerator" with the" \
@@ -89,7 +81,7 @@ epub:
 	@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
 
 
-latex: generate
+latex:
 	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) build/latex
 	@echo
 	@echo "Build finished; the LaTeX files are in build/latex."
@@ -101,21 +93,19 @@ changes:
 	@echo
 	@echo "The overview file is in build/changes."
 
-linkcheck: generate
+linkcheck:
 	$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) build/linkcheck
 	@echo
 	@echo "Link check complete; look for any errors in the above output " \
 	      "or in build/linkcheck/output.txt."
 
-doctest: generate
+doctest:
 	$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) build/doctest
 	@echo "Testing of doctests in the sources finished, look at the " \
 	      "results in build/doctest/output.txt."
 
-gh-pages: clean dist
-	python gh-pages.py $(tag)
-
 gitwash-update:
-	python gitwash_dumper.py source/developer networkx \
-       --project-url=http://networkx.github.io \
-       --project-ml-url=http://groups.google.com/group/networkx-discuss/
+	python ../tools/gitwash_dumper.py source/developer networkx \
+	--project-url=http://networkx.github.io \
+	--project-ml-url=http://groups.google.com/group/networkx-discuss/ \
+	--gitwash-url [email protected]:matthew-brett/gitwash.git