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).
This commit is contained in:
Campbell Barton
@@ -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-
|
||||
|
||||
|
||||
|
||||
@@ -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-
|
||||
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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:
|
||||
|
||||
|
||||
@@ -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
|
||||
"""
|
||||
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user