diff options
Diffstat (limited to 'src/ceph/admin')
-rwxr-xr-x | src/ceph/admin/build-doc | 133 | ||||
-rw-r--r-- | src/ceph/admin/doc-requirements.txt | 3 | ||||
-rw-r--r-- | src/ceph/admin/manpage-howto.txt | 8 | ||||
-rwxr-xr-x | src/ceph/admin/serve-doc | 32 |
4 files changed, 176 insertions, 0 deletions
diff --git a/src/ceph/admin/build-doc b/src/ceph/admin/build-doc new file mode 100755 index 0000000..0caa048 --- /dev/null +++ b/src/ceph/admin/build-doc @@ -0,0 +1,133 @@ +#!/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 python-devel python-pip python-virtualenv doxygen ditaa ant libxml2-devel libxslt-devel Cython graphviz; do + if ! rpm -q $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 --system-site-packages $vdir -p python2 +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 $TOPDIR/src/pybind/${bind} + # rgwfile_version(), librgw_create(), rgw_mount() + nm $vdir/lib/python*/*-packages/${bind}.so | 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 + ;; + man) + extra_opt="-t man" + ;; + esac + $vdir/bin/sphinx-build -a -b $builder $extra_opt -d doctrees \ + $TOPDIR/doc $TOPDIR/build-doc/output/$target +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/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/src/ceph/admin/doc-requirements.txt b/src/ceph/admin/doc-requirements.txt new file mode 100644 index 0000000..dc14113 --- /dev/null +++ b/src/ceph/admin/doc-requirements.txt @@ -0,0 +1,3 @@ +Sphinx == 1.6.3 +-e git+https://github.com/ceph/sphinx-ditaa.git@py3#egg=sphinx-ditaa +-e git+https://github.com/michaeljones/breathe#egg=breathe diff --git a/src/ceph/admin/manpage-howto.txt b/src/ceph/admin/manpage-howto.txt new file mode 100644 index 0000000..ccc78b8 --- /dev/null +++ b/src/ceph/admin/manpage-howto.txt @@ -0,0 +1,8 @@ +Updating the manpages is a semi-manual process: +(all paths below relative to top of git tree): + +1) make changes to the .rst files in doc/man. +2) if adding or removing pages, update man/CMakeLists.txt +3) use admin/build-doc to build the doc tree into build-doc/output +4) copy changed manpage files from build-doc/output/man to man/ +5) commit both doc/man .rst changes and man/ changes diff --git a/src/ceph/admin/serve-doc b/src/ceph/admin/serve-doc new file mode 100755 index 0000000..96da048 --- /dev/null +++ b/src/ceph/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 |