[Bf-blender-cvs] [421ec97] master: Docs: Support out-of-source reference-API builds
Campbell Barton
noreply at git.blender.org
Sun Jun 12 03:28:56 CEST 2016
Commit: 421ec972768b46ba453bb3760b451f05e72a1da6
Author: Campbell Barton
Date: Sun Jun 12 11:20:13 2016 +1000
Branches: master
https://developer.blender.org/rB421ec972768b46ba453bb3760b451f05e72a1da6
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).
===================================================================
M doc/python_api/rst/bge.constraints.rst
M doc/python_api/rst/bge.texture.rst
M doc/python_api/rst/include__bmesh.rst
M doc/python_api/rst/info_quickstart.rst
M doc/python_api/rst_from_bmesh_opdefines.py
M doc/python_api/sphinx_doc_gen.py
M doc/python_api/sphinx_doc_gen.sh
M release/scripts/modules/bpy/utils/previews.py
===================================================================
diff --git a/doc/python_api/rst/bge.constraints.rst b/doc/python_api/rst/bge.constraints.rst
index bf01505..ed965c3 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 0c049a5..f5d325f 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 805d532..dc43d2c 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 1beafd0..f0e1bee 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 ebcedbf..cdbed88 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 9d0d358..74ff23e 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 1ab6bd5..b3bdd38 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}')
+u
@@ Diff output truncated at 10240 characters. @@
More information about the Bf-blender-cvs
mailing list