Docs: Support out-of-source reference-API builds

This was originally supported, however relative links to examples & templates made it fail.
Now files in the source tree are copied to the build-dir, with ".." replaced with "__"
to avoid having to mirror Blender's source-layout in the Sphinx build-dir.

Also skip uploading the built docs when an SSH user-name isn't passed to sphinx_doc_gen.sh
instead of aborting (so people w/o SSH access to our servers can use the shell-script).

7 files changed, 113 insertions, 55 deletions

diff --git a/doc/python_api/rst/bge.constraints.rst b/doc/python_api/rst/bge.constraints.rst
index bf015057dcb..ed965c3dfc1 100644
--- a/doc/python_api/rst/bge.constraints.rst
+++ b/doc/python_api/rst/bge.constraints.rst
@@ -8,11 +8,11 @@ Physics Constraints (bge.constraints)
 Examples
 --------
 
-.. include:: ../examples/bge.constraints.py
+.. include:: __/examples/bge.constraints.py
    :start-line: 1
    :end-line: 4
 
-.. literalinclude:: ../examples/bge.constraints.py
+.. literalinclude:: __/examples/bge.constraints.py
    :lines: 6-
 
 
diff --git a/doc/python_api/rst/bge.texture.rst b/doc/python_api/rst/bge.texture.rst
index 0c049a50fd4..f5d325f7ce8 100644
--- a/doc/python_api/rst/bge.texture.rst
+++ b/doc/python_api/rst/bge.texture.rst
@@ -39,26 +39,26 @@ When the texture object is deleted, the new texture is deleted and the old textu
 
 .. module:: bge.texture
 
-.. include:: ../examples/bge.texture.py
+.. include:: __/examples/bge.texture.py
    :start-line: 1
    :end-line: 5
 
-.. literalinclude:: ../examples/bge.texture.py
+.. literalinclude:: __/examples/bge.texture.py
    :lines: 7-
 
-.. include:: ../examples/bge.texture.1.py
+.. include:: __/examples/bge.texture.1.py
    :start-line: 1
    :end-line: 6
 
-.. literalinclude:: ../examples/bge.texture.1.py
+.. literalinclude:: __/examples/bge.texture.1.py
    :lines: 8-
 
 
-.. include:: ../examples/bge.texture.2.py
+.. include:: __/examples/bge.texture.2.py
    :start-line: 1
    :end-line: 6
 
-.. literalinclude:: ../examples/bge.texture.2.py
+.. literalinclude:: __/examples/bge.texture.2.py
    :lines: 8-
 
 
diff --git a/doc/python_api/rst/include__bmesh.rst b/doc/python_api/rst/include__bmesh.rst
index 805d532eceb..dc43d2c016e 100644
--- a/doc/python_api/rst/include__bmesh.rst
+++ b/doc/python_api/rst/include__bmesh.rst
@@ -41,7 +41,7 @@ For an overview of BMesh data types and how they reference each other see:
 Example Script
 --------------
 
-.. literalinclude:: ../../../release/scripts/templates_py/bmesh_simple.py
+.. literalinclude:: __/__/__/release/scripts/templates_py/bmesh_simple.py
 
 
 Stand-Alone Module
diff --git a/doc/python_api/rst/info_quickstart.rst b/doc/python_api/rst/info_quickstart.rst
index 1beafd06baf..f0e1bee58e7 100644
--- a/doc/python_api/rst/info_quickstart.rst
+++ b/doc/python_api/rst/info_quickstart.rst
@@ -305,7 +305,7 @@ In Python, this is done by defining a class, which is a subclass of an existing
 Example Operator
 ----------------
 
-.. literalinclude:: ../../../release/scripts/templates_py/operator_simple.py
+.. literalinclude:: __/__/__/release/scripts/templates_py/operator_simple.py
 
 Once this script runs, ``SimpleOperator`` is registered with Blender
 and can be called from the operator search popup or added to the toolbar.
@@ -336,7 +336,7 @@ Example Panel
 Panels register themselves as a class, like an operator.
 Notice the extra ``bl_`` variables used to set the context they display in.
 
-.. literalinclude:: ../../../release/scripts/templates_py/ui_panel_simple.py
+.. literalinclude:: __/__/__/release/scripts/templates_py/ui_panel_simple.py
 
 To run the script:
 
diff --git a/doc/python_api/rst_from_bmesh_opdefines.py b/doc/python_api/rst_from_bmesh_opdefines.py
index ebcedbf71f1..cdbed88cc88 100644
--- a/doc/python_api/rst_from_bmesh_opdefines.py
+++ b/doc/python_api/rst_from_bmesh_opdefines.py
@@ -57,7 +57,7 @@ Operator Example
 ++++++++++++++++
 This script shows how operators can be used to model a link of a chain.
 
-.. literalinclude:: ../examples/bmesh.ops.1.py
+.. literalinclude:: __/examples/bmesh.ops.1.py
 """
 
 
diff --git a/doc/python_api/sphinx_doc_gen.py b/doc/python_api/sphinx_doc_gen.py
index 9d0d358305b..74ff23ee2a3 100644
--- a/doc/python_api/sphinx_doc_gen.py
+++ b/doc/python_api/sphinx_doc_gen.py
@@ -325,6 +325,24 @@ except ImportError:
                                                "freestyle.types",
                                                "freestyle.utils"]
 
+# Source files we use, and need to copy to the OUTPUT_DIR
+# to have working out-of-source builds.
+# Note that ".." is replaced by "__" in the RST files,
+# to avoid having to match Blender's source tree.
+EXTRA_SOURCE_FILES = (
+    "../../../release/scripts/templates_py/bmesh_simple.py",
+    "../../../release/scripts/templates_py/operator_simple.py",
+    "../../../release/scripts/templates_py/ui_panel_simple.py",
+    "../../../release/scripts/templates_py/ui_previews_custom_icon.py",
+    "../examples/bge.constraints.py",
+    "../examples/bge.texture.1.py",
+    "../examples/bge.texture.2.py",
+    "../examples/bge.texture.py",
+    "../examples/bmesh.ops.1.py",
+    "../examples/bpy.app.translations.py",
+    )
+
+
 # examples
 EXAMPLES_DIR = os.path.abspath(os.path.join(SCRIPT_DIR, "examples"))
 EXAMPLE_SET = set()
@@ -1890,6 +1908,21 @@ def copy_handwritten_rsts(basepath):
             shutil.copy2(os.path.join(RST_DIR, f), basepath)
 
 
+def copy_handwritten_extra(basepath):
+    for f_src in EXTRA_SOURCE_FILES:
+        if os.sep != "/":
+            f_src = os.sep.join(f_src.split("/"))
+
+        f_dst = f_src.replace("..", "__")
+
+        f_src = os.path.join(RST_DIR, f_src)
+        f_dst = os.path.join(basepath, f_dst)
+
+        os.makedirs(os.path.dirname(f_dst), exist_ok=True)
+
+        shutil.copy2(f_src, f_dst)
+
+
 def rna2sphinx(basepath):
 
     try:
@@ -1921,35 +1954,48 @@ def rna2sphinx(basepath):
     # copy the other rsts
     copy_handwritten_rsts(basepath)
 
+    # copy source files referenced
+    copy_handwritten_extra(basepath)
+
 
-def align_sphinx_in_to_sphinx_in_tmp():
+def align_sphinx_in_to_sphinx_in_tmp(dir_src, dir_dst):
     '''
     Move changed files from SPHINX_IN_TMP to SPHINX_IN
     '''
     import filecmp
 
-    sphinx_in_files = set(os.listdir(SPHINX_IN))
-    sphinx_in_tmp_files = set(os.listdir(SPHINX_IN_TMP))
+    # possible the dir doesn't exist when running recursively
+    os.makedirs(dir_dst, exist_ok=True)
+
+    sphinx_dst_files = set(os.listdir(dir_dst))
+    sphinx_src_files = set(os.listdir(dir_src))
 
     # remove deprecated files that have been removed
-    for f in sorted(sphinx_in_files):
-        if f not in sphinx_in_tmp_files:
+    for f in sorted(sphinx_dst_files):
+        if f not in sphinx_src_files:
             BPY_LOGGER.debug("\tdeprecated: %s" % f)
-            os.remove(os.path.join(SPHINX_IN, f))
+            f_dst = os.path.join(dir_dst, f)
+            if os.path.isdir(f_dst):
+                shutil.rmtree(f_dst, True)
+            else:
+                os.remove(f_dst)
 
     # freshen with new files.
-    for f in sorted(sphinx_in_tmp_files):
-        f_from = os.path.join(SPHINX_IN_TMP, f)
-        f_to = os.path.join(SPHINX_IN, f)
+    for f in sorted(sphinx_src_files):
+        f_src = os.path.join(dir_src, f)
+        f_dst = os.path.join(dir_dst, f)
 
-        do_copy = True
-        if f in sphinx_in_files:
-            if filecmp.cmp(f_from, f_to):
-                do_copy = False
+        if os.path.isdir(f_src):
+            align_sphinx_in_to_sphinx_in_tmp(f_src, f_dst)
+        else:
+            do_copy = True
+            if f in sphinx_dst_files:
+                if filecmp.cmp(f_src, f_dst):
+                    do_copy = False
 
-        if do_copy:
-            BPY_LOGGER.debug("\tupdating: %s" % f)
-            shutil.copy(f_from, f_to)
+            if do_copy:
+                BPY_LOGGER.debug("\tupdating: %s" % f)
+                shutil.copy(f_src, f_dst)
 
 
 def refactor_sphinx_log(sphinx_logfile):
@@ -2036,7 +2082,7 @@ def main():
             shutil.rmtree(SPHINX_OUT_PDF, True)
     else:
         # move changed files in SPHINX_IN
-        align_sphinx_in_to_sphinx_in_tmp()
+        align_sphinx_in_to_sphinx_in_tmp(SPHINX_IN_TMP, SPHINX_IN)
 
     # report which example files weren't used
     EXAMPLE_SET_UNUSED = EXAMPLE_SET - EXAMPLE_SET_USED
diff --git a/doc/python_api/sphinx_doc_gen.sh b/doc/python_api/sphinx_doc_gen.sh
index 1ab6bd5afc7..b3bdd386f8c 100755
--- a/doc/python_api/sphinx_doc_gen.sh
+++ b/doc/python_api/sphinx_doc_gen.sh
@@ -3,11 +3,6 @@
 #   bash doc/python_api/sphinx_doc_gen.sh
 # ssh upload means you need an account on the server
 
-if [ "$1" == "" ] ; then
-	echo "Expected a single argument for the username on blender.org, aborting"
-	exit 1
-fi
-
 # ----------------------------------------------------------------------------
 # Upload vars
 
@@ -22,9 +17,15 @@ if [ -z $BLENDER_BIN ] ; then
 	BLENDER_BIN="./blender.bin"
 fi
 
-SSH_USER=$1
-SSH_HOST=$SSH_USER"@blender.org"
-SSH_UPLOAD="/data/www/vhosts/www.blender.org/api" # blender_python_api_VERSION, added after
+if [ "$1" == "" ] ; then
+	echo "Expected a single argument for the username on blender.org, skipping upload step!"
+	DO_UPLOAD=false
+else
+	SSH_USER=$1
+	SSH_HOST=$SSH_USER"@blender.org"
+	SSH_UPLOAD="/data/www/vhosts/www.blender.org/api" # blender_python_api_VERSION, added after
+fi
+
 
 # ----------------------------------------------------------------------------
 # Blender Version & Info
@@ -33,10 +34,12 @@ SSH_UPLOAD="/data/www/vhosts/www.blender.org/api" # blender_python_api_VERSION,
 # "_".join(str(v) for v in bpy.app.version)
 # custom blender vars
 blender_srcdir=$(dirname -- $0)/../..
-blender_version=$(grep "BLENDER_VERSION\s" "$blender_srcdir/source/blender/blenkernel/BKE_blender_version.h" | awk '{print $3}')
-blender_version_char=$(grep "BLENDER_VERSION_CHAR\s" "$blender_srcdir/source/blender/blenkernel/BKE_blender_version.h" | awk '{print $3}')
-blender_version_cycle=$(grep "BLENDER_VERSION_CYCLE\s" "$blender_srcdir/source/blender/blenkernel/BKE_blender_version.h" | awk '{print $3}')
-blender_subversion=$(grep "BLENDER_SUBVERSION\s" "$blender_srcdir/source/blender/blenkernel/BKE_blender_version.h" | awk '{print $3}')
+blender_version_header="$blender_srcdir/source/blender/blenkernel/BKE_blender_version.h"
+blender_version=$(grep "BLENDER_VERSION\s" "$blender_version_header" | awk '{print $3}')
+blender_version_char=$(grep "BLENDER_VERSION_CHAR\s" "$blender_version_header" | awk '{print $3}')
+blender_version_cycle=$(grep "BLENDER_VERSION_CYCLE\s" "$blender_version_header" | awk '{print $3}')
+blender_subversion=$(grep "BLENDER_SUBVERSION\s" "$blender_version_header" | awk '{print $3}')
+unset blender_version_header
 
 if [ "$blender_version_cycle" = "release" ] ; then
 	BLENDER_VERSION=$(expr $blender_version / 100)_$(expr $blender_version % 100)$blender_version_char"_release"
@@ -48,6 +51,8 @@ SSH_UPLOAD_FULL=$SSH_UPLOAD/"blender_python_api_"$BLENDER_VERSION
 
 SPHINXBASE=doc/python_api
 
+SPHINX_WORKDIR="$(mktemp --directory --suffix=.sphinx)"
+
 
 # ----------------------------------------------------------------------------
 # Generate reStructuredText (blender/python only)
@@ -59,7 +64,10 @@ if $DO_EXE_BLENDER ; then
 		-noaudio \
 		--factory-startup \
 		--python-exit-code 1 \
-		--python $SPHINXBASE/sphinx_doc_gen.py
+		--python $SPHINXBASE/sphinx_doc_gen.py \
+		-- \
+		--output=$SPHINX_WORKDIR
+
 
 	if (($? != 0)) ; then
 		echo "Generating documentation failed, aborting"
@@ -67,15 +75,14 @@ if $DO_EXE_BLENDER ; then
 	fi
 fi
 
-
 # ----------------------------------------------------------------------------
 # Generate HTML (sphinx)
 
 if $DO_OUT_HTML ; then
-	# sphinx-build -n -b html $SPHINXBASE/sphinx-in $SPHINXBASE/sphinx-out
+	# sphinx-build -n -b html $SPHINX_WORKDIR/sphinx-in $SPHINX_WORKDIR/sphinx-out
 
 	# annoying bug in sphinx makes it very slow unless we do this. should report.
-	cd $SPHINXBASE
+	cd $SPHINX_WORKDIR
 	sphinx-build -b html sphinx-in sphinx-out
 
 	# XXX, saves space on upload and zip, should move HTML outside
@@ -103,20 +110,21 @@ fi
 # Generate PDF (sphinx/laytex)
 
 if $DO_OUT_PDF ; then
-	sphinx-build -n -b latex $SPHINXBASE/sphinx-in $SPHINXBASE/sphinx-out
-	make -C $SPHINXBASE/sphinx-out
-	mv $SPHINXBASE/sphinx-out/contents.pdf $SPHINXBASE/sphinx-out/blender_python_reference_$BLENDER_VERSION.pdf
+	cd $SPHINX_WORKDIR
+	sphinx-build -n -b latex $SPHINX_WORKDIR/sphinx-in $SPHINX_WORKDIR/sphinx-out
+	make -C $SPHINX_WORKDIR/sphinx-out
+	mv $SPHINX_WORKDIR/sphinx-out/contents.pdf \
+	   $SPHINX_WORKDIR/sphinx-out/blender_python_reference_$BLENDER_VERSION.pdf
 fi
 
-
 # ----------------------------------------------------------------------------
 # Upload to blender servers, comment this section for testing
 
 if $DO_UPLOAD ; then
 
-	cp $SPHINXBASE/sphinx-out/contents.html $SPHINXBASE/sphinx-out/index.html
+	cp $SPHINX_WORKDIR/sphinx-out/contents.html $SPHINX_WORKDIR/sphinx-out/index.html
 	ssh $SSH_USER@blender.org 'rm -rf '$SSH_UPLOAD_FULL'/*'
-	rsync --progress -ave "ssh -p 22" $SPHINXBASE/sphinx-out/* $SSH_HOST:$SSH_UPLOAD_FULL/
+	rsync --progress -ave "ssh -p 22" $SPHINX_WORKDIR/sphinx-out/* $SSH_HOST:$SSH_UPLOAD_FULL/
 
 	## symlink the dir to a static URL
 	#ssh $SSH_USER@blender.org 'rm '$SSH_UPLOAD'/250PythonDoc && ln -s '$SSH_UPLOAD_FULL' '$SSH_UPLOAD'/250PythonDoc'
@@ -134,11 +142,15 @@ if $DO_UPLOAD ; then
 
 	if $DO_OUT_PDF ; then
 		# rename so local PDF has matching name.
-		rsync --progress -ave "ssh -p 22" $SPHINXBASE/sphinx-out/blender_python_reference_$BLENDER_VERSION.pdf $SSH_HOST:$SSH_UPLOAD_FULL/blender_python_reference_$BLENDER_VERSION.pdf
+		rsync --progress -ave "ssh -p 22" \
+		      $SPHINX_WORKDIR/sphinx-out/blender_python_reference_$BLENDER_VERSION.pdf \
+		      $SSH_HOST:$SSH_UPLOAD_FULL/blender_python_reference_$BLENDER_VERSION.pdf
 	fi
 
 	if $DO_OUT_HTML_ZIP ; then
-		rsync --progress -ave "ssh -p 22" $SPHINXBASE/blender_python_reference_$BLENDER_VERSION.zip $SSH_HOST:$SSH_UPLOAD_FULL/blender_python_reference_$BLENDER_VERSION.zip
+		rsync --progress -ave "ssh -p 22" \
+		      $SPHINX_WORKDIR/blender_python_reference_$BLENDER_VERSION.zip \
+		      $SSH_HOST:$SSH_UPLOAD_FULL/blender_python_reference_$BLENDER_VERSION.zip
 	fi
 
 fi
@@ -149,5 +161,5 @@ fi
 
 echo ""
 echo "Finished! view the docs from: "
-if $DO_OUT_HTML ; then echo "  html:" $SPHINXBASE/sphinx-out/contents.html ; fi
-if $DO_OUT_PDF ; then  echo "   pdf:" $SPHINXBASE/sphinx-out/blender_python_reference_$BLENDER_VERSION.pdf ; fi
+if $DO_OUT_HTML ; then echo "  html:" $SPHINX_WORKDIR/sphinx-out/contents.html ; fi
+if $DO_OUT_PDF ; then  echo "   pdf:" $SPHINX_WORKDIR/sphinx-out/blender_python_reference_$BLENDER_VERSION.pdf ; fi