summaryrefslogtreecommitdiffstats
path: root/admin
diff options
context:
space:
mode:
Diffstat (limited to 'admin')
-rwxr-xr-xadmin/build-doc122
-rw-r--r--admin/doc-pybind.txt4
-rw-r--r--admin/doc-python-common-requirements.txt1
-rw-r--r--admin/doc-read-the-docs.txt2
-rw-r--r--admin/doc-requirements.txt15
-rwxr-xr-xadmin/serve-doc33
6 files changed, 177 insertions, 0 deletions
diff --git a/admin/build-doc b/admin/build-doc
new file mode 100755
index 000000000..345324a14
--- /dev/null
+++ b/admin/build-doc
@@ -0,0 +1,122 @@
+#!/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-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 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
+
+[ -z "$vdir" ] && vdir="$TOPDIR/build-doc/virtualenv"
+
+if [ ! -e $vdir ]; then
+ python3 -m venv $vdir
+fi
+
+$vdir/bin/pip install --quiet wheel
+$vdir/bin/pip install --quiet \
+ -r $TOPDIR/admin/doc-requirements.txt \
+ -r $TOPDIR/admin/doc-python-common-requirements.txt
+BUILD_DOC=1 $vdir/bin/pip install --quiet \
+ -r $TOPDIR/admin/doc-pybind.txt
+
+install -d -m0755 \
+ $TOPDIR/build-doc/output/html \
+ $TOPDIR/build-doc/output/man
+
+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
+
+cd build-doc
+
+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)
+ $vdir/bin/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"
diff --git a/admin/doc-pybind.txt b/admin/doc-pybind.txt
new file mode 100644
index 000000000..9ec4acfcf
--- /dev/null
+++ b/admin/doc-pybind.txt
@@ -0,0 +1,4 @@
+src/pybind/rados
+src/pybind/cephfs
+src/pybind/rbd
+src/pybind/rgw
diff --git a/admin/doc-python-common-requirements.txt b/admin/doc-python-common-requirements.txt
new file mode 100644
index 000000000..21ca6e85c
--- /dev/null
+++ b/admin/doc-python-common-requirements.txt
@@ -0,0 +1 @@
+src/python-common
diff --git a/admin/doc-read-the-docs.txt b/admin/doc-read-the-docs.txt
new file mode 100644
index 000000000..7e0ecc86d
--- /dev/null
+++ b/admin/doc-read-the-docs.txt
@@ -0,0 +1,2 @@
+plantweb
+git+https://github.com/readthedocs/readthedocs-sphinx-search@main
diff --git a/admin/doc-requirements.txt b/admin/doc-requirements.txt
new file mode 100644
index 000000000..dec096a86
--- /dev/null
+++ b/admin/doc-requirements.txt
@@ -0,0 +1,15 @@
+Sphinx == 4.4.0
+git+https://github.com/ceph/sphinx-ditaa.git@py3#egg=sphinx-ditaa
+breathe >= 4.20.0
+Jinja2
+pyyaml >= 5.1.2
+Cython
+pcpp
+prettytable
+sphinx-autodoc-typehints
+sphinx-prompt
+sphinx_rtd_theme == 1.0.0
+Sphinx-Substitution-Extensions
+typed-ast
+sphinxcontrib-openapi
+mistune < 2.0.0
diff --git a/admin/serve-doc b/admin/serve-doc
new file mode 100755
index 000000000..fa2805938
--- /dev/null
+++ b/admin/serve-doc
@@ -0,0 +1,33 @@
+#!/usr/bin/python3
+
+from __future__ import print_function
+
+import http.server
+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(http.server.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 http.server.SimpleHTTPRequestHandler.send_head(self)
+
+httpd = socketserver.TCPServer(
+ ("", 8080),
+ ReusingTCPServer,
+ )
+try:
+ print("Serving doc at port: http://localhost:8080")
+ httpd.serve_forever()
+except KeyboardInterrupt:
+ pass