diff options
Diffstat (limited to 'admin')
| -rwxr-xr-x | admin/build-doc | 161 | ||||
| -rw-r--r-- | admin/doc-read-the-docs.txt | 2 | ||||
| -rw-r--r-- | admin/doc-requirements.txt | 4 | ||||
| -rwxr-xr-x | admin/serve-doc | 32 |
4 files changed, 199 insertions, 0 deletions
diff --git a/admin/build-doc b/admin/build-doc new file mode 100755 index 00000000..7a23c7d4 --- /dev/null +++ b/admin/build-doc @@ -0,0 +1,161 @@ +#!/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 + python_package="python$(rpm --eval '%{python3_pkgversion}')" + for package in "$python_package"-devel "$python_package"-pip "$python_package"-virtualenv doxygen ditaa ant libxml2-devel libxslt-devel "$python_package"-Cython graphviz; 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 virtualenv doxygen ant ditaa cython; do + command -v "$command" > /dev/null; + ret_code=$? + if [ $ret_code -ne 0 ]; 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" + exit 1 + fi +fi + +# Don't enable -e until after running all the potentially-erroring checks +# for availability of commands +set -e + +cat $TOPDIR/src/osd/PG.h $TOPDIR/src/osd/PG.cc | $TOPDIR/doc/scripts/gen_state_diagram.py > $TOPDIR/doc/dev/peering_graph.generated.dot + +cd build-doc + +[ -z "$vdir" ] && vdir="$TOPDIR/build-doc/virtualenv" + +if [ ! -e $vdir ]; then + virtualenv --python=python3 --system-site-packages $vdir +fi +$vdir/bin/pip install --quiet -r $TOPDIR/admin/doc-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 + +# 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 + if [ ${bind} != rados ]; then + cp -f $TOPDIR/src/pybind/rados/rados.pxd $TOPDIR/src/pybind/${bind}/ + fi + ln -sf lib${bind}.so.1 $vdir/lib/lib${bind}.so + gcc -shared -o $vdir/lib/lib${bind}.so.1 -xc /dev/null + BUILD_DOC=1 \ + CFLAGS="-iquote$TOPDIR/src/include" \ + CPPFLAGS="-iquote$TOPDIR/src/include" \ + LDFLAGS="-L$vdir/lib -Wl,--no-as-needed" \ + $vdir/bin/pip install --upgrade $TOPDIR/src/pybind/${bind} + # rgwfile_version(), librgw_create(), rgw_mount() + # since py3.5, distutils adds postfix in between ${bind} and so + lib_fn=$vdir/lib/python*/*-packages/${bind}.*.so + if [ ! -e $lib_fn ]; then + lib_fn=$vdir/lib/python*/*-packages/${bind}.so + fi + nm $lib_fn | grep -E "U (lib)?${bind}" | \ + awk '{ print "void "$2"(void) {}" }' | \ + gcc -shared -o $vdir/lib/lib${bind}.so.1 -xc - + if [ ${bind} != rados ]; then + rm -f $TOPDIR/src/pybind/${bind}/rados.pxd + fi +done + +if [ -z "$@" ]; then + sphinx_targets="html man" +else + sphinx_targets=$@ +fi +for target in $sphinx_targets; do + builder=$target + case $target in + html) + builder=dirhtml + extra_opt="-D graphviz_output_format=svg" + ;; + man) + extra_opt="-t man" + ;; + esac + # Build with -W so that warnings are treated as errors and this fails + $vdir/bin/sphinx-build -W -a -b $builder $extra_opt -d doctrees \ + $TOPDIR/doc $TOPDIR/build-doc/output/$target + + +done + +# build the releases.json. this reads in the yaml version and dumps +# out the json representation of the same file. the resulting releases.json +# should be served from the root of hosted site. +$vdir/bin/python << EOF > $TOPDIR/build-doc/output/html/releases.json +from __future__ import print_function +import datetime +import json +import yaml + +def json_serialize(obj): + if isinstance(obj, datetime.date): + return obj.isoformat() + +with open("$TOPDIR/doc/releases/releases.yml", 'r') as fp: + releases = yaml.load(fp) + print(json.dumps(releases, indent=2, default=json_serialize)) +EOF + +# +# 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/api/libcephfs-java/javadoc +rm -rf $JAVA_OUTDIR +mkdir $JAVA_OUTDIR + +# Copy JavaDocs to target directory +cp -a $JAVADIR/doc/* $JAVA_OUTDIR/ diff --git a/admin/doc-read-the-docs.txt b/admin/doc-read-the-docs.txt new file mode 100644 index 00000000..b65cc463 --- /dev/null +++ b/admin/doc-read-the-docs.txt @@ -0,0 +1,2 @@ +plantweb +git+https://github.com/readthedocs/readthedocs-sphinx-search@master diff --git a/admin/doc-requirements.txt b/admin/doc-requirements.txt new file mode 100644 index 00000000..0af3bde9 --- /dev/null +++ b/admin/doc-requirements.txt @@ -0,0 +1,4 @@ +Sphinx == 2.1.2 +git+https://github.com/ceph/sphinx-ditaa.git@py3#egg=sphinx-ditaa +breathe == 4.13.1 +pyyaml >= 5.1.2 diff --git a/admin/serve-doc b/admin/serve-doc new file mode 100755 index 00000000..96da048e --- /dev/null +++ b/admin/serve-doc @@ -0,0 +1,32 @@ +#!/usr/bin/python +from __future__ import print_function + +import SimpleHTTPServer +import SocketServer +import os +import sys + +path = os.path.dirname(sys.argv[0]) +os.chdir(path) +os.chdir('..') +os.chdir('build-doc/output/html') + +class ReusingTCPServer(SimpleHTTPServer.SimpleHTTPRequestHandler): + allow_reuse_address = True + + def send_head(self): + # horrible kludge because SimpleHTTPServer is buggy wrt + # slash-redirecting of requests with query arguments, and will + # redirect to /foo?q=bar/ -- wrong slash placement + self.path = self.path.split('?', 1)[0] + return SimpleHTTPServer.SimpleHTTPRequestHandler.send_head(self) + +httpd = SocketServer.TCPServer( + ("", 8080), + ReusingTCPServer, + ) +try: + print("Serving doc at port: http://localhost:8080") + httpd.serve_forever() +except KeyboardInterrupt: + pass |