mirror of
https://github.com/ceph/ceph
synced 2024-12-27 14:03:25 +00:00
34f74e8a37
it is time-consuming to rebuild the python bindings every time we rebuild the document, it'd be ideal if we could just build document. in this change, in addition to "html" and "doc", "livehtml" argument is now supported by build-doc script, so one can just use ./build-doc livehtml to build and start a web server. whenever a change in doc/ is detected, the document is rebuilt. for more details, see https://pypi.org/project/sphinx-autobuild/ Signed-off-by: Kefu Chai <kchai@redhat.com>
143 lines
4.3 KiB
Bash
Executable File
143 lines
4.3 KiB
Bash
Executable File
#!/bin/sh
|
|
|
|
cd "$(dirname "$0")"
|
|
cd ..
|
|
TOPDIR=`pwd`
|
|
|
|
install -d -m0755 build-doc
|
|
|
|
if command -v dpkg >/dev/null; then
|
|
packages=`cat ${TOPDIR}/doc_deps.deb.txt`
|
|
for package in $packages; do
|
|
if [ "$(dpkg --status -- $package 2>&1 | sed -n 's/^Status: //p')" != "install ok installed" ]; then
|
|
# add a space after old values
|
|
missing="${missing:+$missing }$package"
|
|
fi
|
|
done
|
|
if [ -n "$missing" ]; then
|
|
echo "$0: missing required packages, please install them:" 1>&2
|
|
echo "sudo apt-get install -o APT::Install-Recommends=true $missing" 1>&2
|
|
exit 1
|
|
fi
|
|
elif command -v yum >/dev/null; then
|
|
for package in ant ditaa doxygen libxslt-devel libxml2-devel graphviz python3-devel python3-pip python3-virtualenv python3-Cython; do
|
|
if ! rpm -q --whatprovides $package >/dev/null ; then
|
|
missing="${missing:+$missing }$package"
|
|
fi
|
|
done
|
|
if [ -n "$missing" ]; then
|
|
echo "$0: missing required packages, please install them:" 1>&2
|
|
echo "yum install $missing"
|
|
exit 1
|
|
fi
|
|
else
|
|
for command in dot virtualenv doxygen ant ditaa cython; do
|
|
if ! command -v "$command" > /dev/null; then
|
|
# add a space after old values
|
|
missing="${missing:+$missing }$command"
|
|
fi
|
|
done
|
|
if [ -n "$missing" ]; then
|
|
echo "$0: missing required command, please install them:" 1>&2
|
|
echo "$missing" 1>&2
|
|
exit 1
|
|
fi
|
|
fi
|
|
|
|
# Don't enable -e until after running all the potentially-erroring checks
|
|
# for availability of commands
|
|
set -e
|
|
|
|
cd build-doc
|
|
|
|
[ -z "$vdir" ] && vdir="$TOPDIR/build-doc/virtualenv"
|
|
|
|
if [ ! -e $vdir ]; then
|
|
virtualenv --python=python3 $vdir
|
|
fi
|
|
|
|
# be compatible with pip shipped by distro older v20.2
|
|
if $vdir/bin/pip --use-feature=2020-resolver >/dev/null 2>&1 ; then
|
|
PIP_INSTALL="$vdir/bin/pip install --use-feature=2020-resolver"
|
|
else
|
|
PIP_INSTALL="$vdir/bin/pip install"
|
|
fi
|
|
$PIP_INSTALL --quiet -r $TOPDIR/admin/doc-requirements.txt -r $TOPDIR/admin/doc-python-common-requirements.txt
|
|
|
|
install -d -m0755 \
|
|
$TOPDIR/build-doc/output/html \
|
|
$TOPDIR/build-doc/output/man
|
|
|
|
# To avoid having to build librbd to build the Python bindings to build the docs,
|
|
# create a dummy librbd.so that allows the module to be imported by sphinx.
|
|
# the module are imported by the "automodule::" directive.
|
|
mkdir -p $vdir/lib
|
|
export LD_LIBRARY_PATH="$vdir/lib"
|
|
export PYTHONPATH=$TOPDIR/src/pybind
|
|
|
|
|
|
$vdir/bin/python $TOPDIR/doc/scripts/gen_mon_command_api.py > $TOPDIR/doc/api/mon_command_api.rst
|
|
|
|
|
|
# FIXME(sileht): I dunno how to pass the include-dirs correctly with pip
|
|
# for build_ext step, it should be:
|
|
# --global-option=build_ext --global-option="--cython-include-dirs $TOPDIR/src/pybind/rados/"
|
|
# but that doesn't work, so copying the file in the rbd module directly, that's ok for docs
|
|
for bind in rados rbd cephfs rgw; do
|
|
BUILD_DOC=1 $vdir/bin/pip install --upgrade $TOPDIR/src/pybind/${bind}
|
|
done
|
|
|
|
for opt in "$@"; do
|
|
case $opt in
|
|
html|man|livehtml)
|
|
sphinx_targets="$sphinx_targets $opt"
|
|
shift
|
|
;;
|
|
--)
|
|
shift
|
|
break
|
|
esac
|
|
done
|
|
|
|
if [ -z "$sphinx_targets" ]; then
|
|
sphinx_targets="html man"
|
|
fi
|
|
|
|
for target in $sphinx_targets; do
|
|
# Build with -W so that warnings are treated as errors and this fails
|
|
case $target in
|
|
html)
|
|
$vdir/bin/sphinx-build -W --keep-going -a -b dirhtml -d doctrees \
|
|
$TOPDIR/doc $TOPDIR/build-doc/output/$target
|
|
;;
|
|
man)
|
|
$vdir/bin/sphinx-build -W --keep-going -a -b man -t man -d doctrees \
|
|
$TOPDIR/doc $TOPDIR/build-doc/output/$target
|
|
;;
|
|
livehtml)
|
|
$PIP_INSTALL --quiet sphinx-autobuild
|
|
$vdir/bin/sphinx-autobuild --re-ignore '.*\.dot' "$@" \
|
|
$TOPDIR/doc $TOPDIR/build-doc/output/html
|
|
;;
|
|
esac
|
|
done
|
|
|
|
#
|
|
# Build and install JavaDocs
|
|
#
|
|
JAVADIR=$TOPDIR/src/java
|
|
|
|
# Clean and build JavaDocs
|
|
rm -rf $JAVADIR/doc
|
|
ant -buildfile $JAVADIR/build.xml docs
|
|
|
|
# Create clean target directory
|
|
JAVA_OUTDIR=$TOPDIR/build-doc/output/html/cephfs/api/libcephfs-java/javadoc
|
|
rm -rf $JAVA_OUTDIR
|
|
mkdir $JAVA_OUTDIR
|
|
|
|
# Copy JavaDocs to target directory
|
|
cp -a $JAVADIR/doc/* $JAVA_OUTDIR/
|
|
|
|
echo "SUCCESS"
|