[Doc] Fix document building for multiple tensor backends (dmlc#301)

* remove loading backend in sse

* build mxnet in a second run

* a third run to fix everything

* fix docstring in sampler

* fix docstring in transformer

* README for doc build

* some reordering and printing

* use filename_pattern instead of ignore_pattern to reduce warning at the cost of redundant work...

* add env var to use mxnet in Jenkinsfile

* remove step 3, it's already fixed by previous commit

Jenkinsfile

@@ -55,7 +55,7 @@ def pytorch_tutorials() {
 }
 
 def mxnet_tutorials() {
-  withEnv(["DGL_LIBRARY_PATH=${env.WORKSPACE}/build", "PYTHONPATH=${env.WORKSPACE}/python"]) {
+  withEnv(["DGL_LIBRARY_PATH=${env.WORKSPACE}/build", "PYTHONPATH=${env.WORKSPACE}/python", "DGLBACKEND=mxnet"]) {
     dir("tests/scripts") {
       sh "bash task_mxnet_tutorial_test.sh"
     }

docs/Makefile

@@ -13,12 +13,32 @@ help:
 
 .PHONY: help Makefile
 
+mxnet:
+	@echo "##################################################################"
+	@echo "#                                                                #"
+	@echo "#                Step 1: Building MXNet tutorials                #"
+	@echo "#                                                                #"
+	@echo "##################################################################"
+	@DGLBACKEND=mxnet $(SPHINXBUILD) -M html "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) \
+						 -D sphinx_gallery_conf.filename_pattern="/*(?<=mx)\.py"
+
+pytorch:
+	@echo "##################################################################"
+	@echo "#                                                                #"
+	@echo "#                Step 2: Building PyTorch tutorials              #"
+	@echo "#                                                                #"
+	@echo "##################################################################"
+	@DGLBACKEND=pytorch $(SPHINXBUILD) -M html "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) \
+						 -D sphinx_gallery_conf.filename_pattern="/*(?<!mx)\.py"
+
 html-noexec:
 	$(SPHINXBUILD) -D plot_gallery=0 -b html "$(SOURCEDIR)" "$(BUILDDIR)/html" 
 	@echo
 	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
 
+html: Makefile mxnet pytorch
+
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
 %: Makefile
-	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) 

docs/README.md

@@ -1,9 +1,25 @@
 DGL document and tutorial folder
 ================================
 
-To build,
+Build documents
+---------------
+First, clean up existing files:
+```
+./clean.sh
+```
+
+Then build:
 ```
 make html
 ```
 
-and then render the page `build/html/index.html`.
+Note: due to the backend loading issue, it actually takes 2 rounds to build:
+1. build tutorials that uses MXNet as backend
+2. build tutorials that uses PyTorch as backend
+
+Render locally
+--------------
+```
+cd build/html
+python3 -m http.server 8000
+```

python/dgl/contrib/sampling/sampler.py

@@ -99,8 +99,10 @@ def NeighborSampler(g, batch_size, expand_factor, num_hops=1,
 
     The subgraph loader returns a list of subgraphs and a dictionary of additional
     information about the subgraphs. The size of the subgraph list is the number of workers.
+
     The dictionary contains:
-        'seeds': a list of 1D tensors of seed Ids, if return_seed_id is True.
+
+    - seeds: a list of 1D tensors of seed Ids, if return_seed_id is True.
 
     Parameters
     ----------

tutorials/models/1_gnn/8_sse_mx.py

@@ -92,9 +92,6 @@
 import mxnet as mx
 import os
 import dgl
-# DGL backend defaults to PyTorch, so we need to switch backend.
-# One can also set the environment variable outside Python.
-dgl.load_backend('mxnet')
 
 def T(g):
     def message_func(edges):

tutorials/models/4_old_wines/7_transformer.py

@@ -219,12 +219,12 @@
 # function, including:
 #
 # - ``fn.src_mul_egdes(src_field, edges_field, out_field)`` multiplies
-# source’s attribute and edges attribute, and send the result to the
-# destination node’s mailbox keyed by ``out_field``.
+#   source’s attribute and edges attribute, and send the result to the
+#   destination node’s mailbox keyed by ``out_field``.
 # - ``fn.copy_edge(edges_field, out_field)`` copies edge’s attribute to
-# destination node’s mailbox.
+#   destination node’s mailbox.
 # - ``fn.sum(edges_field, out_field)`` sums up
-# edge’s attribute and sends aggregation to destination node’s mailbox.
+#   edge’s attribute and sends aggregation to destination node’s mailbox.
 #
 # Here we assemble those built-in function into ``propagate_attention``,
 # which is also the main graph operation function in our final
@@ -540,6 +540,7 @@
 #        print(graph.tgt[0]) # Output word index list
 #        print(graph.tgt[1]) # Ouptut positions
 #        break
+#
 # Output:
 #
 # .. code::