mirror of
https://github.com/openvswitch/ovs
synced 2025-08-22 09:58:01 +00:00
dist-docs: New utility to generate a documentation bundle for the website.
This utility isn't going to be as portable as most of the Open vSwitch utilities, unfortunately. I'm happy to take improvements to make it able to work with, e.g., the "man" program from BSD. (I haven't tested with that program, but I suspect that it is somewhat different from the GNU version.) The output of this program can already be viewed at: http://openvswitch.org/support/dist-docs/ Signed-off-by: Ben Pfaff <blp@nicira.com> Acked-by: Thomas Graf <tgraf@noironetworks.com>
This commit is contained in:
Ben Pfaff
parent
e3639cbd4f
commit
4441a01cbd
16
Makefile.am
16
Makefile.am
@ -61,7 +61,10 @@ CLEANFILES =
|
||||
CLEAN_LOCAL =
|
||||
DISTCLEANFILES =
|
||||
PYCOV_CLEAN_FILES = build-aux/check-structs,cover
|
||||
EXTRA_DIST = \
|
||||
|
||||
# A list of Markdown-formatted documentation that will automatically be
|
||||
# included in the "make dist-docs" output.
|
||||
docs = \
|
||||
CONTRIBUTING.md \
|
||||
CodingStyle.md \
|
||||
DESIGN.md \
|
||||
@ -80,7 +83,6 @@ EXTRA_DIST = \
|
||||
INSTALL.userspace.md \
|
||||
INSTALL.Windows.md \
|
||||
IntegrationGuide.md \
|
||||
NOTICE \
|
||||
OPENFLOW-1.1+.md \
|
||||
PORTING.md \
|
||||
README.md \
|
||||
@ -88,12 +90,16 @@ EXTRA_DIST = \
|
||||
README-native-tunneling.md \
|
||||
REPORTING-BUGS.md \
|
||||
TODO.md \
|
||||
WHY-OVS.md
|
||||
EXTRA_DIST = \
|
||||
$(docs) \
|
||||
NOTICE \
|
||||
.travis.yml \
|
||||
.travis/build.sh \
|
||||
.travis/prepare.sh \
|
||||
WHY-OVS.md \
|
||||
boot.sh \
|
||||
build-aux/cccl \
|
||||
build-aux/dist-docs \
|
||||
build-aux/sodepends.pl \
|
||||
build-aux/soexpand.pl \
|
||||
$(MAN_FRAGMENTS) \
|
||||
@ -337,6 +343,10 @@ if LINUX_ENABLED
|
||||
cd datapath/linux && $(MAKE) modules_install
|
||||
endif
|
||||
|
||||
dist-docs:
|
||||
VERSION=$(VERSION) $(srcdir)/build-aux/dist-docs $(srcdir) $(docs)
|
||||
.PHONY: dist-docs
|
||||
|
||||
include m4/automake.mk
|
||||
include lib/automake.mk
|
||||
include ofproto/automake.mk
|
||||
|
||||
153
build-aux/dist-docs
Executable file
153
build-aux/dist-docs
Executable file
@ -0,0 +1,153 @@
|
||||
#! /bin/sh
|
||||
|
||||
set -e
|
||||
|
||||
# Check command line.
|
||||
if test ! -d "$1" || test $# -lt 2; then
|
||||
cat <<EOF
|
||||
$0: HTML documentation generator for Open vSwitch
|
||||
usage: $0 srcdir docfile...
|
||||
|
||||
The VERSION environment variable should be set to the Open vSwitch version.
|
||||
Must be invoked from an Open vSwitch build directory.
|
||||
Most conveniently invoked via "make dist-docs".
|
||||
EOF
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# Parse command line.
|
||||
srcdir=$1
|
||||
shift
|
||||
|
||||
# Check for programs we'll need.
|
||||
search_path () {
|
||||
save_IFS=$IFS
|
||||
IFS=:
|
||||
for dir in $PATH; do
|
||||
IFS=$save_IFS
|
||||
if test -x "$dir/$1"; then
|
||||
return 0
|
||||
fi
|
||||
done
|
||||
IFS=$save_IFS
|
||||
echo >&2 "$0: $1 not found in \$PATH, please install and try again"
|
||||
exit 1
|
||||
}
|
||||
search_path man
|
||||
search_path markdown
|
||||
search_path ps2pdf
|
||||
|
||||
# Create dist-docs directory.
|
||||
distdir=dist-docs
|
||||
abs_distdir=`pwd`/dist-docs
|
||||
rm -rf $distdir
|
||||
mkdir $distdir
|
||||
|
||||
# Install manpages.
|
||||
make install-man mandir="$abs_distdir"/man
|
||||
(cd $distdir && mv `find man -type f` . && rm -rf man)
|
||||
manpages=`cd $distdir && echo *`
|
||||
|
||||
# Start writing index.html.
|
||||
exec 3>$distdir/index.html
|
||||
cat >&3 <<EOF
|
||||
<html><head>
|
||||
<meta charset="UTF-8"></head>
|
||||
<link rel="stylesheet" type="text/css" href="style.css">
|
||||
<title>Open vSwitch $VERSION Documentation</title>
|
||||
</head><body>
|
||||
<h1>Open vSwitch $VERSION Documentation</h1>
|
||||
<h2>Documents</h2>
|
||||
<table>
|
||||
EOF
|
||||
|
||||
# Add top-level documentation to index.html, giving it .txt extensions so
|
||||
# that the webserver doesn't serve it as Markdown and make your web browser
|
||||
# try to invoke some kind of external helper you don't have installed.
|
||||
#
|
||||
# Also translate documentation to HTML.
|
||||
for file
|
||||
do
|
||||
title=`head -1 "$srcdir/$file"`
|
||||
dir=$distdir/`dirname $file`; test -d "$dir" || mkdir "$dir"
|
||||
cp "$srcdir/$file" "$distdir/$file.txt"
|
||||
(cat <<EOF
|
||||
<html><head>
|
||||
<meta charset="UTF-8"></head>
|
||||
<link rel="stylesheet" type="text/css" href="style.css">
|
||||
<title>$file (Open vSwitch $VERSION)</title>
|
||||
</head><body>
|
||||
EOF
|
||||
markdown "$distdir/$file.txt"
|
||||
echo "</body></html>") > "$distdir/$file.html"
|
||||
cat <<EOF
|
||||
<tr>
|
||||
<td>$file</td>
|
||||
<td>$title</td>
|
||||
<td><a href="$file.html">HTML</a>, <a href="$file.txt">plain text</a></td>
|
||||
</tr>
|
||||
EOF
|
||||
done >&3
|
||||
|
||||
# Add header for manpages to index.html.
|
||||
cat >&3 <<EOF
|
||||
</table>
|
||||
<h2>Manpages</h2>
|
||||
<table>
|
||||
EOF
|
||||
|
||||
# Add manpages to index.html, translating them into PDF, HTML, and plain text.
|
||||
# The HTML is just slightly marked up from the plain text version; although
|
||||
# groff supports better HTML output, on my system some of the OVS manpages
|
||||
# cause the groff HTML output engine to segfault (!).
|
||||
(cd $distdir
|
||||
for manpage in $manpages; do
|
||||
man -l -Tps $manpage | ps2pdf - > $manpage.pdf
|
||||
man -l -Tutf8 $manpage | sed 's/.//g' > $manpage.txt
|
||||
(echo '<html><head><meta charset="UTF-8"></head><body><pre>'
|
||||
man -l -Tutf8 $manpage | sed '
|
||||
s/&/&/g
|
||||
s/</</g
|
||||
s/>/>/g
|
||||
s,\(.\)\1,<b>\1</b>,g
|
||||
s,_\(.\),<u>\1</u>,g'
|
||||
echo '</pre></body></html>'
|
||||
) > $manpage.html
|
||||
|
||||
name=`echo $manpage | sed 's/\.\([0-9]\)$/(\1)/'`
|
||||
echo " <tr><td>$name</td><td><a href=\"$manpage.pdf\">PDF</a>, <a href=\"$manpage.html\">HTML</a>, <a href=\"$manpage.txt\">plain text</a></td></tr>"
|
||||
done
|
||||
) >&3
|
||||
cat >&3 <<EOF
|
||||
</table>
|
||||
</body></html>
|
||||
EOF
|
||||
|
||||
# Create CSS style file.
|
||||
cat >$distdir/style.css <<'EOF'
|
||||
div { vertical-align:top; }
|
||||
p {
|
||||
vertical-align:baseline;
|
||||
}
|
||||
a {
|
||||
text-decoration: none;
|
||||
font-weight: 700;
|
||||
}
|
||||
a:hover {
|
||||
color:#444;
|
||||
}
|
||||
a:visited {
|
||||
color:#447099;
|
||||
}
|
||||
a:link {
|
||||
color:#447099;
|
||||
}
|
||||
|
||||
body {
|
||||
font-family: Arial,Helvetica,sans-serif;
|
||||
font-size: 14px;
|
||||
line-height: 1.5em;
|
||||
color: #444;
|
||||
background-color:#f5f5f5;
|
||||
}
|
||||
EOF
|
||||
@ -174,6 +174,7 @@ utilities/ovs-testcontroller.8: \
|
||||
utilities/ovs-testcontroller.8.in \
|
||||
lib/common.man \
|
||||
lib/daemon.man \
|
||||
lib/ofp-version.man \
|
||||
lib/ssl-peer-ca-cert.man \
|
||||
lib/ssl.man \
|
||||
lib/unixctl.man \
|
||||
@ -183,6 +184,7 @@ utilities/ovs-testcontroller.8: \
|
||||
utilities/ovs-testcontroller.8.in:
|
||||
lib/common.man:
|
||||
lib/daemon.man:
|
||||
lib/ofp-version.man:
|
||||
lib/ssl-peer-ca-cert.man:
|
||||
lib/ssl.man:
|
||||
lib/unixctl.man:
|
||||
|
||||
5
third-party/automake.mk
vendored
5
third-party/automake.mk
vendored
@ -1,3 +1,2 @@
|
||||
EXTRA_DIST += \
|
||||
third-party/README.md \
|
||||
third-party/ofp-tcpdump.patch
|
||||
docs += third-party/README.md
|
||||
EXTRA_DIST += third-party/ofp-tcpdump.patch
|
||||
|
||||
@ -1,5 +1,5 @@
|
||||
docs += tutorial/Tutorial.md
|
||||
EXTRA_DIST += \
|
||||
tutorial/Tutorial.md \
|
||||
tutorial/ovs-sandbox \
|
||||
tutorial/t-setup \
|
||||
tutorial/t-stage0 \
|
||||
|
||||
@ -24,11 +24,11 @@ scripts_DATA += utilities/ovs-lib
|
||||
|
||||
utilities/ovs-lib: $(top_builddir)/config.status
|
||||
|
||||
docs += utilities/ovs-command-compgen.INSTALL.md
|
||||
EXTRA_DIST += \
|
||||
utilities/ovs-check-dead-ifs.in \
|
||||
utilities/ovs-command-compgen.bash \
|
||||
utilities/ovs-command-compgen-test.bash \
|
||||
utilities/ovs-command-compgen.INSTALL.md \
|
||||
utilities/ovs-ctl.in \
|
||||
utilities/ovs-dev.py \
|
||||
utilities/ovs-docker \
|
||||
|
||||
@ -17,9 +17,8 @@ vtep_vtep_ctl_LDADD = lib/libopenvswitch.la
|
||||
scripts_SCRIPTS += \
|
||||
vtep/ovs-vtep
|
||||
|
||||
EXTRA_DIST += \
|
||||
vtep/ovs-vtep \
|
||||
vtep/README.ovs-vtep.md
|
||||
docs += vtep/README.ovs-vtep.md
|
||||
EXTRA_DIST += vtep/ovs-vtep
|
||||
|
||||
# VTEP schema and IDL
|
||||
EXTRA_DIST += vtep/vtep.ovsschema
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user