LU-5657 doc: allow the use of rst2man to build man pages

The man page sources can now be written in reStructuredText (rst), and
the man pages will automatically be generated with rst2man.

Added a build dependency on rst2man and the package python-docutils.

Converted lustreapi.7 to ReST to validate the solution.

Change-Id: I69e9892a238a002eb86769ed65b758cba55543bb
Signed-off-by: frank zago <fzago@cray.com>
Reviewed-on: http://review.whamcloud.com/12040
Tested-by: Jenkins
Tested-by: Maloo <hpdd-maloo@intel.com>
Reviewed-by: Andreas Dilger <andreas.dilger@intel.com>
Reviewed-by: Patrick Farrell <paf@cray.com>
Reviewed-by: Oleg Drokin <oleg.drokin@intel.com>

diff --git a/config/lustre-build.m4 b/config/lustre-build.m4
index d9217bf..3745d92 100644 (file)
--- a/config/lustre-build.m4
+++ b/config/lustre-build.m4
@@ -626,6 +626,12 @@ LC_CONFIG_CLIENT
 LB_CONFIG_MPITESTS
 LB_CONFIG_SERVERS
 
+AC_CHECK_PROGS(RST2MAN, [rst2man rst2man.py], [])
+if test "x$RST2MAN" = "x"; then
+  AC_MSG_ERROR(
+    [rst2man is needed to build the man pages. Install python-docutils.])
+fi
+
 # Tests depends from utils (multiop from liblustreapi)
 AS_IF([test "x$enable_utils" = xno], [enable_tests="no"])
 

diff --git a/lustre.spec.in b/lustre.spec.in
index 6b84c0b..5c5fc6d 100644 (file)
--- a/lustre.spec.in
+++ b/lustre.spec.in
@@ -106,7 +106,7 @@ BuildRoot: %{_tmppath}/lustre-%{version}-root
 Obsoletes: lustre-lite, lustre-lite-utils, lustre-ldap nfs-utils-lustre
 Provides: lustre-lite = %{version}, lustre-lite-utils = %{version}
 Requires: %{name}-modules = %{version}
-BuildRequires: libtool
+BuildRequires: libtool python-docutils
 %if %{with servers}
 Requires: lustre-osd
 Requires: lustre-osd-mount

diff --git a/lustre/doc/Makefile.am b/lustre/doc/Makefile.am
index cc6a5ad..1a62342 100644 (file)
--- a/lustre/doc/Makefile.am
+++ b/lustre/doc/Makefile.am
@@ -68,8 +68,11 @@ if UTILS
 man_MANS = $(MANFILES)
 endif
 
+.rst.3 .rst.7:
+       @RST2MAN@ $? $@
+
 CLEANFILES = *.aux *.tex *.log *.pdf
 
-EXTRA_DIST = $(MANFILES) $(DISTONLY_MANFILES)
+EXTRA_DIST = $(MANFILES) *.rst $(DISTONLY_MANFILES)
 
 all:

diff --git a/lustre/doc/lustreapi.7 b/lustre/doc/lustreapi.7
deleted file mode 100644 (file)
index 17eb982..0000000
--- a/lustre/doc/lustreapi.7
+++ /dev/null
@@ -1,14 +0,0 @@
-.TH lustreapi 7 "2009 Aug 10" The Lustre user application interface library
-.SH NAME
-lustreapi \- The lustre API library
-.SH DESCRIPTION
-The lustreapi library provides functions to access and/or modify settings specific to the Lustre filesystem (allocation policies, quotas, etc).
-.SH "SEE ALSO"
-.BR lustre (7),
-.BR llapi_file_create (3),
-.BR llapi_file_open (3),
-.BR llapi_file_get_stripe (3),
-.BR llapi_layout (3),
-.BR llapi_quotactl (3)
-.BR llapi_hsm_state_get (3)
-.BR llapi_hsm_state_set (3)

diff --git a/lustre/doc/lustreapi.rst b/lustre/doc/lustreapi.rst
new file mode 100644 (file)
index 0000000..bc0da2c
--- /dev/null
+++ b/lustre/doc/lustreapi.rst
@@ -0,0 +1,36 @@
+=========
+lustreapi
+=========
+
+----------------------
+The Lustre API library
+----------------------
+
+:Author: Lustre contributors
+:Date:   2009-08-10
+:Manual section: 7
+:Manual group: The Lustre API library
+
+SYNOPSIS
+========
+
+**#include <lustre/lustreapi.h>**
+
+DESCRIPTION
+===========
+
+The lustreapi library provides functions to access and/or modify
+settings specific to the Lustre filesystem (allocation policies,
+quotas, etc).
+
+SEE ALSO
+========
+
+**lustre**\ (7),
+**llapi_file_create**\ (3),
+**llapi_file_open**\ (3),
+**llapi_file_get_stripe**\ (3),
+**llapi_layout**\ (3),
+**llapi_quotactl**\ (3),
+**llapi_hsm_state_get**\ (3),
+**llapi_hsm_state_set**\ (3)