Docs: Support out-of-source reference-API builds
authorCampbell Barton <ideasman42@gmail.com>
Sun, 12 Jun 2016 01:20:13 +0000 (11:20 +1000)
committerCampbell Barton <ideasman42@gmail.com>
Sun, 12 Jun 2016 01:31:28 +0000 (11:31 +1000)
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).

doc/python_api/rst/bge.constraints.rst
doc/python_api/rst/bge.texture.rst
doc/python_api/rst/include__bmesh.rst
doc/python_api/rst/info_quickstart.rst
doc/python_api/rst_from_bmesh_opdefines.py
doc/python_api/sphinx_doc_gen.py
doc/python_api/sphinx_doc_gen.sh
release/scripts/modules/bpy/utils/previews.py

index bf015057dcb80cf9409c6c77aedb5dd23c793d71..ed965c3dfc1d8bdfbfc21a7dd37e10204ac30636 100644 (file)
@@ -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-
 
 
index 0c049a50fd4929274ff2eabcff05af4a9172f984..f5d325f7ce879358483f3825796f26f4c37698e4 100644 (file)
@@ -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-
 
 
index 805d532ecebf4b2ca3d01b659caad54165f936f3..dc43d2c016eed0189b3ab2904748578a783960d4 100644 (file)
@@ -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
index 1beafd06baf52cb42de250f6612e0eba6f6a3b46..f0e1bee58e7f54b1c3aa34fbf774e92bd2fa11f0 100644 (file)
@@ -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:
 
index ebcedbf71f15da206d114cfd8f4b786f0927a897..cdbed88cc88e3f8f4169c301b94788690b40d859 100644 (file)
@@ -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
 """
 
 
index 9d0d358305baa08270215a994ed1d90d15c77b70..74ff23ee2a34f8f612450d57d988a4905b1231c4 100644 (file)
@@ -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
index 1ab6bd5afc772b3f7f76c1fc0dab65ddee5099e9..b3bdd386f8cc707bd02e7a9dd008206010901d91 100755 (executable)
@@ -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
index c67c523ea72e40d4bfd78bb45de21e71b97f60d6..568116b027cc06141dd31b1bf516273e68111716 100644 (file)
@@ -30,7 +30,7 @@ This allows scripts to generate their own previews, and use them as icons in UI
 Custom Icon Example
 -------------------
 
-.. literalinclude:: ../../../release/scripts/templates_py/ui_previews_custom_icon.py
+.. literalinclude:: __/__/__/release/scripts/templates_py/ui_previews_custom_icon.py
 """
 
 __all__ = (