Cr8-xyz/blender
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

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

Browse Source 
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
2016-06-12 11:20:13 +10:00
parent 2b15a588a1
commit 421ec97276
8 changed files with 114 additions and 56 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
doc/python_api/rst/bge.constraints.rst
View File

@@ -8,11 +8,11 @@ Physics Constraints (bge.constraints)
Examples Examples
-------- --------
.. include:: ../examples/bge.constraints.py .. include:: __/examples/bge.constraints.py
:start-line: 1 :start-line: 1
:end-line: 4 :end-line: 4
.. literalinclude:: ../examples/bge.constraints.py .. literalinclude:: __/examples/bge.constraints.py
:lines: 6- :lines: 6-

12
doc/python_api/rst/bge.texture.rst
View File

@@ -39,26 +39,26 @@ When the texture object is deleted, the new texture is deleted and the old textu
.. module:: bge.texture .. module:: bge.texture
.. include:: ../examples/bge.texture.py .. include:: __/examples/bge.texture.py
:start-line: 1 :start-line: 1
:end-line: 5 :end-line: 5
.. literalinclude:: ../examples/bge.texture.py .. literalinclude:: __/examples/bge.texture.py
:lines: 7- :lines: 7-
.. include:: ../examples/bge.texture.1.py .. include:: __/examples/bge.texture.1.py
:start-line: 1 :start-line: 1
:end-line: 6 :end-line: 6
.. literalinclude:: ../examples/bge.texture.1.py .. literalinclude:: __/examples/bge.texture.1.py
:lines: 8- :lines: 8-
.. include:: ../examples/bge.texture.2.py .. include:: __/examples/bge.texture.2.py
:start-line: 1 :start-line: 1
:end-line: 6 :end-line: 6
.. literalinclude:: ../examples/bge.texture.2.py .. literalinclude:: __/examples/bge.texture.2.py
:lines: 8- :lines: 8-

2
doc/python_api/rst/include__bmesh.rst
View File

@@ -41,7 +41,7 @@ For an overview of BMesh data types and how they reference each other see:
Example Script Example Script
-------------- --------------
.. literalinclude:: ../../../release/scripts/templates_py/bmesh_simple.py .. literalinclude:: __/__/__/release/scripts/templates_py/bmesh_simple.py
Stand-Alone Module Stand-Alone Module

4
doc/python_api/rst/info_quickstart.rst
View File

@@ -305,7 +305,7 @@ In Python, this is done by defining a class, which is a subclass of an existing
Example Operator 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 Once this script runs, ``SimpleOperator`` is registered with Blender
and can be called from the operator search popup or added to the toolbar. 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. Panels register themselves as a class, like an operator.
Notice the extra ``bl_`` variables used to set the context they display in. 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: To run the script:

2
doc/python_api/rst_from_bmesh_opdefines.py
View File

@@ -57,7 +57,7 @@ Operator Example
++++++++++++++++ ++++++++++++++++
This script shows how operators can be used to model a link of a chain. 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
""" """

80
doc/python_api/sphinx_doc_gen.py
View File

@@ -325,6 +325,24 @@ except ImportError:
"freestyle.types", "freestyle.types",
"freestyle.utils"] "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
EXAMPLES_DIR = os.path.abspath(os.path.join(SCRIPT_DIR, "examples")) EXAMPLES_DIR = os.path.abspath(os.path.join(SCRIPT_DIR, "examples"))
EXAMPLE_SET = set() EXAMPLE_SET = set()
@@ -1890,6 +1908,21 @@ def copy_handwritten_rsts(basepath):
shutil.copy2(os.path.join(RST_DIR, f), 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): def rna2sphinx(basepath):
try: try:
@@ -1921,35 +1954,48 @@ def rna2sphinx(basepath):
# copy the other rsts # copy the other rsts
copy_handwritten_rsts(basepath) 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 Move changed files from SPHINX_IN_TMP to SPHINX_IN
''' '''
import filecmp import filecmp
sphinx_in_files = set(os.listdir(SPHINX_IN)) # possible the dir doesn't exist when running recursively
sphinx_in_tmp_files = set(os.listdir(SPHINX_IN_TMP)) 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 # remove deprecated files that have been removed
for f in sorted(sphinx_in_files): for f in sorted(sphinx_dst_files):
if f not in sphinx_in_tmp_files: if f not in sphinx_src_files:
BPY_LOGGER.debug("\tdeprecated: %s" % f) 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. # freshen with new files.
for f in sorted(sphinx_in_tmp_files): for f in sorted(sphinx_src_files):
f_from = os.path.join(SPHINX_IN_TMP, f) f_src = os.path.join(dir_src, f)
f_to = os.path.join(SPHINX_IN, f) f_dst = os.path.join(dir_dst, f)
do_copy = True if os.path.isdir(f_src):
if f in sphinx_in_files: align_sphinx_in_to_sphinx_in_tmp(f_src, f_dst)
if filecmp.cmp(f_from, f_to): else:
do_copy = False do_copy = True
if f in sphinx_dst_files:
if filecmp.cmp(f_src, f_dst):
do_copy = False
if do_copy: if do_copy:
BPY_LOGGER.debug("\tupdating: %s" % f) BPY_LOGGER.debug("\tupdating: %s" % f)
shutil.copy(f_from, f_to) shutil.copy(f_src, f_dst)
def refactor_sphinx_log(sphinx_logfile): def refactor_sphinx_log(sphinx_logfile):
@@ -2036,7 +2082,7 @@ def main():
shutil.rmtree(SPHINX_OUT_PDF, True) shutil.rmtree(SPHINX_OUT_PDF, True)
else: else:
# move changed files in SPHINX_IN # 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 # report which example files weren't used
EXAMPLE_SET_UNUSED = EXAMPLE_SET - EXAMPLE_SET_USED EXAMPLE_SET_UNUSED = EXAMPLE_SET - EXAMPLE_SET_USED

64
doc/python_api/sphinx_doc_gen.sh
View File

@@ -3,11 +3,6 @@
# bash doc/python_api/sphinx_doc_gen.sh # bash doc/python_api/sphinx_doc_gen.sh
# ssh upload means you need an account on the server # 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 # Upload vars
@@ -22,9 +17,15 @@ if [ -z $BLENDER_BIN ] ; then
BLENDER_BIN="./blender.bin" BLENDER_BIN="./blender.bin"
fi fi
SSH_USER=$1 if [ "$1" == "" ] ; then
SSH_HOST=$SSH_USER"@blender.org" echo "Expected a single argument for the username on blender.org, skipping upload step!"
SSH_UPLOAD="/data/www/vhosts/www.blender.org/api" # blender_python_api_VERSION, added after 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 # 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) # "_".join(str(v) for v in bpy.app.version)
# custom blender vars # custom blender vars
blender_srcdir=$(dirname -- $0)/../.. blender_srcdir=$(dirname -- $0)/../..
blender_version=$(grep "BLENDER_VERSION\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_char=$(grep "BLENDER_VERSION_CHAR\s" "$blender_srcdir/source/blender/blenkernel/BKE_blender_version.h" | awk '{print $3}') blender_version=$(grep "BLENDER_VERSION\s" "$blender_version_header" | awk '{print $3}')
blender_version_cycle=$(grep "BLENDER_VERSION_CYCLE\s" "$blender_srcdir/source/blender/blenkernel/BKE_blender_version.h" | awk '{print $3}') blender_version_char=$(grep "BLENDER_VERSION_CHAR\s" "$blender_version_header" | awk '{print $3}')
blender_subversion=$(grep "BLENDER_SUBVERSION\s" "$blender_srcdir/source/blender/blenkernel/BKE_blender_version.h" | 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 if [ "$blender_version_cycle" = "release" ] ; then
BLENDER_VERSION=$(expr $blender_version / 100)_$(expr $blender_version % 100)$blender_version_char"_release" 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 SPHINXBASE=doc/python_api
SPHINX_WORKDIR="$(mktemp --directory --suffix=.sphinx)"
# ---------------------------------------------------------------------------- # ----------------------------------------------------------------------------
# Generate reStructuredText (blender/python only) # Generate reStructuredText (blender/python only)
@@ -59,7 +64,10 @@ if $DO_EXE_BLENDER ; then
-noaudio \ -noaudio \
--factory-startup \ --factory-startup \
--python-exit-code 1 \ --python-exit-code 1 \
--python $SPHINXBASE/sphinx_doc_gen.py --python $SPHINXBASE/sphinx_doc_gen.py \
-- \
--output=$SPHINX_WORKDIR
if (($? != 0)) ; then if (($? != 0)) ; then
echo "Generating documentation failed, aborting" echo "Generating documentation failed, aborting"
@@ -67,15 +75,14 @@ if $DO_EXE_BLENDER ; then
fi fi
fi fi
# ---------------------------------------------------------------------------- # ----------------------------------------------------------------------------
# Generate HTML (sphinx) # Generate HTML (sphinx)
if $DO_OUT_HTML ; then 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. # 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 sphinx-build -b html sphinx-in sphinx-out
# XXX, saves space on upload and zip, should move HTML outside # XXX, saves space on upload and zip, should move HTML outside
@@ -103,20 +110,21 @@ fi
# Generate PDF (sphinx/laytex) # Generate PDF (sphinx/laytex)
if $DO_OUT_PDF ; then if $DO_OUT_PDF ; then
sphinx-build -n -b latex $SPHINXBASE/sphinx-in $SPHINXBASE/sphinx-out cd $SPHINX_WORKDIR
make -C $SPHINXBASE/sphinx-out sphinx-build -n -b latex $SPHINX_WORKDIR/sphinx-in $SPHINX_WORKDIR/sphinx-out
mv $SPHINXBASE/sphinx-out/contents.pdf $SPHINXBASE/sphinx-out/blender_python_reference_$BLENDER_VERSION.pdf make -C $SPHINX_WORKDIR/sphinx-out
mv $SPHINX_WORKDIR/sphinx-out/contents.pdf \
$SPHINX_WORKDIR/sphinx-out/blender_python_reference_$BLENDER_VERSION.pdf
fi fi
# ---------------------------------------------------------------------------- # ----------------------------------------------------------------------------
# Upload to blender servers, comment this section for testing # Upload to blender servers, comment this section for testing
if $DO_UPLOAD ; then 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'/*' 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 ## symlink the dir to a static URL
#ssh $SSH_USER@blender.org 'rm '$SSH_UPLOAD'/250PythonDoc && ln -s '$SSH_UPLOAD_FULL' '$SSH_UPLOAD'/250PythonDoc' #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 if $DO_OUT_PDF ; then
# rename so local PDF has matching name. # 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 fi
if $DO_OUT_HTML_ZIP ; then 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
fi fi
@@ -149,5 +161,5 @@ fi
echo "" echo ""
echo "Finished! view the docs from: " echo "Finished! view the docs from: "
if $DO_OUT_HTML ; then echo " html:" $SPHINXBASE/sphinx-out/contents.html ; fi if $DO_OUT_HTML ; then echo " html:" $SPHINX_WORKDIR/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_PDF ; then echo " pdf:" $SPHINX_WORKDIR/sphinx-out/blender_python_reference_$BLENDER_VERSION.pdf ; fi

2
release/scripts/modules/bpy/utils/previews.py
View File

@@ -30,7 +30,7 @@ This allows scripts to generate their own previews, and use them as icons in UI
Custom Icon Example Custom Icon Example
------------------- -------------------
.. literalinclude:: ../../../release/scripts/templates_py/ui_previews_custom_icon.py .. literalinclude:: __/__/__/release/scripts/templates_py/ui_previews_custom_icon.py
""" """
__all__ = ( __all__ = (