4b7569f7d5499dc555319d3a153ca61bfda3bbc6
[blender.git] / doc / python_api / sphinx_doc_gen.sh
1 #!/bin/sh
2 # run from the blender source dir
3 #   bash doc/python_api/sphinx_doc_gen.sh
4 # ssh upload means you need an account on the server
5
6 # ----------------------------------------------------------------------------
7 # Upload vars
8
9 # disable for testing
10 DO_UPLOAD=true
11 DO_EXE_BLENDER=true
12 DO_OUT_HTML=true
13 DO_OUT_HTML_ZIP=true
14 DO_OUT_PDF=false
15
16 if [ -z $BLENDER_BIN ] ; then
17         BLENDER_BIN="./blender.bin"
18 fi
19
20 if [ "$1" == "" ] ; then
21         echo "Expected a single argument for the username on blender.org, skipping upload step!"
22         DO_UPLOAD=false
23 else
24         SSH_USER=$1
25         SSH_HOST=$SSH_USER"@blender.org"
26         SSH_UPLOAD="/data/www/vhosts/www.blender.org/api" # blender_python_api_VERSION, added after
27 fi
28
29
30 # ----------------------------------------------------------------------------
31 # Blender Version & Info
32
33 # 'Blender 2.53 (sub 1) Build' --> '2_53_1' as a shell script.
34 # "_".join(str(v) for v in bpy.app.version)
35 # custom blender vars
36 blender_srcdir=$(dirname -- $0)/../..
37 blender_version_header="$blender_srcdir/source/blender/blenkernel/BKE_blender_version.h"
38 blender_version=$(grep "BLENDER_VERSION\s" "$blender_version_header" | awk '{print $3}')
39 blender_version_char=$(grep "BLENDER_VERSION_CHAR\s" "$blender_version_header" | awk '{print $3}')
40 blender_version_cycle=$(grep "BLENDER_VERSION_CYCLE\s" "$blender_version_header" | awk '{print $3}')
41 blender_subversion=$(grep "BLENDER_SUBVERSION\s" "$blender_version_header" | awk '{print $3}')
42 unset blender_version_header
43
44 if [ "$blender_version_cycle" = "release" ] ; then
45         BLENDER_VERSION=$(expr $blender_version / 100)_$(expr $blender_version % 100)$blender_version_char"_release"
46 else
47         BLENDER_VERSION=$(expr $blender_version / 100)_$(expr $blender_version % 100)_$blender_subversion
48 fi
49
50 SSH_UPLOAD_FULL=$SSH_UPLOAD/"blender_python_api_"$BLENDER_VERSION
51
52 SPHINXBASE=doc/python_api
53
54 SPHINX_WORKDIR="$(mktemp --directory --suffix=.sphinx)"
55
56
57 # ----------------------------------------------------------------------------
58 # Generate reStructuredText (blender/python only)
59
60 if $DO_EXE_BLENDER ; then
61         # Don't delete existing docs, now partial updates are used for quick builds.
62         #
63         # Disable ASAN error halt since it results in nonzero exit code on any minor issue.
64         ASAN_OPTIONS=halt_on_error=0 \
65         $BLENDER_BIN \
66                 --background \
67                 -noaudio \
68                 --factory-startup \
69                 --python-exit-code 1 \
70                 --python $SPHINXBASE/sphinx_doc_gen.py \
71                 -- \
72                 --output=$SPHINX_WORKDIR
73
74
75         if (($? != 0)) ; then
76                 echo "Generating documentation failed, aborting"
77                 exit 1
78         fi
79 fi
80
81 # ----------------------------------------------------------------------------
82 # Generate HTML (sphinx)
83
84 if $DO_OUT_HTML ; then
85         # sphinx-build -n -b html $SPHINX_WORKDIR/sphinx-in $SPHINX_WORKDIR/sphinx-out
86
87         # annoying bug in sphinx makes it very slow unless we do this. should report.
88         cd $SPHINX_WORKDIR
89         sphinx-build -b html sphinx-in sphinx-out
90
91         # XXX, saves space on upload and zip, should move HTML outside
92         # and zip up there, for now this is OK
93         rm -rf sphinx-out/.doctrees
94
95         # in case we have a zip already
96         rm -f blender_python_reference_$BLENDER_VERSION.zip
97
98         # ------------------------------------------------------------------------
99         # ZIP the HTML dir for upload
100
101         if $DO_OUT_HTML_ZIP ; then
102                 # lame, temp rename dir
103                 mv sphinx-out blender_python_reference_$BLENDER_VERSION
104                 zip -r -9 blender_python_reference_$BLENDER_VERSION.zip blender_python_reference_$BLENDER_VERSION
105                 mv blender_python_reference_$BLENDER_VERSION sphinx-out
106         fi
107
108         cd -
109 fi
110
111
112 # ----------------------------------------------------------------------------
113 # Generate PDF (sphinx/laytex)
114
115 if $DO_OUT_PDF ; then
116         cd $SPHINX_WORKDIR
117         sphinx-build -n -b latex $SPHINX_WORKDIR/sphinx-in $SPHINX_WORKDIR/sphinx-out
118         make -C $SPHINX_WORKDIR/sphinx-out
119         mv $SPHINX_WORKDIR/sphinx-out/contents.pdf \
120            $SPHINX_WORKDIR/sphinx-out/blender_python_reference_$BLENDER_VERSION.pdf
121 fi
122
123 # ----------------------------------------------------------------------------
124 # Upload to blender servers, comment this section for testing
125
126 if $DO_UPLOAD ; then
127
128         ssh $SSH_USER@blender.org 'rm -rf '$SSH_UPLOAD_FULL'/*'
129         rsync --progress -ave "ssh -p 22" $SPHINX_WORKDIR/sphinx-out/* $SSH_HOST:$SSH_UPLOAD_FULL/
130
131         ## symlink the dir to a static URL
132         #ssh $SSH_USER@blender.org 'rm '$SSH_UPLOAD'/250PythonDoc && ln -s '$SSH_UPLOAD_FULL' '$SSH_UPLOAD'/250PythonDoc'
133         if [ "$blender_version_cycle" = "release" ] ; then
134                 ssh $SSH_USER@blender.org 'rm '$SSH_UPLOAD'/blender_python_api_current && ln -s '$SSH_UPLOAD_FULL' '$SSH_UPLOAD'/blender_python_api_current'
135         fi
136
137         # better redirect
138         ssh $SSH_USER@blender.org 'echo "<html><head><title>Redirecting...</title><meta http-equiv=\"REFRESH\" content=\"0;url=../blender_python_api_'$BLENDER_VERSION'/\"></head><body>Redirecting...</body></html>" > '$SSH_UPLOAD'/250PythonDoc/index.html'
139
140         # redirect for release only so wiki can point here
141         if [ "$blender_version_cycle" = "release" ] ; then
142                 ssh $SSH_USER@blender.org 'echo "<html><head><title>Redirecting...</title><meta http-equiv=\"REFRESH\" content=\"0;url=../blender_python_api_'$BLENDER_VERSION'/\"></head><body>Redirecting...</body></html>" > '$SSH_UPLOAD'/blender_python_api/index.html'
143         fi
144
145         if $DO_OUT_PDF ; then
146                 # rename so local PDF has matching name.
147                 rsync --progress -ave "ssh -p 22" \
148                       $SPHINX_WORKDIR/sphinx-out/blender_python_reference_$BLENDER_VERSION.pdf \
149                       $SSH_HOST:$SSH_UPLOAD_FULL/blender_python_reference_$BLENDER_VERSION.pdf
150         fi
151
152         if $DO_OUT_HTML_ZIP ; then
153                 rsync --progress -ave "ssh -p 22" \
154                       $SPHINX_WORKDIR/blender_python_reference_$BLENDER_VERSION.zip \
155                       $SSH_HOST:$SSH_UPLOAD_FULL/blender_python_reference_$BLENDER_VERSION.zip
156         fi
157
158 fi
159
160
161 # ----------------------------------------------------------------------------
162 # Print some useful text
163
164 echo ""
165 echo "Finished! view the docs from: "
166 if $DO_OUT_HTML ; then echo "  html:" $SPHINX_WORKDIR/sphinx-out/index.html ; fi
167 if $DO_OUT_PDF ; then  echo "   pdf:" $SPHINX_WORKDIR/sphinx-out/blender_python_reference_$BLENDER_VERSION.pdf ; fi