diff options
Diffstat (limited to 'doc')
-rw-r--r-- | doc/python_api/rst/bge.constraints.rst | 4 | ||||
-rw-r--r-- | doc/python_api/rst/bge.texture.rst | 12 | ||||
-rw-r--r-- | doc/python_api/rst/include__bmesh.rst | 2 | ||||
-rw-r--r-- | doc/python_api/rst/info_quickstart.rst | 4 | ||||
-rw-r--r-- | doc/python_api/rst_from_bmesh_opdefines.py | 2 | ||||
-rw-r--r-- | doc/python_api/sphinx_doc_gen.py | 80 | ||||
-rwxr-xr-x | doc/python_api/sphinx_doc_gen.sh | 64 |
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 |