doc: generate man pages in man/Makefile

* move rst files from doc/man/8 into man/8
* extract man_pages setting for sphinx from doc/conf.py to man/conf.py
* generate all man pages in `make install`
* add python-sphinx to Build-Depends
* check for sphinx-build in `configure`
* run changed rst files through sphinx-build in `make check`

Signed-off-by: Kefu Chai <kchai@redhat.com>

ceph.spec.in

@@ -60,6 +60,7 @@ BuildRequires:	python
 BuildRequires:	python-argparse
 BuildRequires:	python-nose
 BuildRequires:	python-requests
+BuildRequires:	python-sphinx
 BuildRequires:	python-virtualenv
 BuildRequires:	util-linux
 BuildRequires:	xfsprogs

configure.ac

@@ -21,6 +21,11 @@ if test -d ".git" ; then
 fi
 AC_MSG_NOTICE([RPM_RELEASE='$RPM_RELEASE'])
 
+AC_CHECK_PROG(SPHINX_BUILD, sphinx-build, yes, no)
+if test x"$SPHINX_BUILD" = x"no"; then
+  AC_MSG_ERROR([sphinx-build not found (python-sphinx)])
+fi
+
 AC_CONFIG_MACRO_DIR([m4])
 
 AC_CONFIG_SUBDIRS([src/gmock])

debian/control

@@ -46,6 +46,7 @@ Build-Depends: autoconf,
                python (>= 2.6.6-3~),
                python-argparse,
                python-nose,
+               python-sphinx,
                python-virtualenv,
                sdparm | hdparm,
                uuid-dev,

doc/conf.py

@@ -32,43 +32,6 @@ extensions = [
     ]
 todo_include_todos = True
 
-def _get_manpages():
-    import os
-    man_dir = os.path.join(
-        os.path.dirname(__file__),
-        'man',
-        )
-    sections = os.listdir(man_dir)
-    for section in sections:
-        section_dir = os.path.join(man_dir, section)
-        if not os.path.isdir(section_dir):
-            continue
-        for filename in os.listdir(section_dir):
-            base, ext = os.path.splitext(filename)
-            if ext != '.rst':
-                continue
-            if base == 'index':
-                continue
-            with file(os.path.join(section_dir, filename)) as f:
-                one = f.readline()
-                two = f.readline()
-                three = f.readline()
-                assert one == three
-                assert all(c=='=' for c in one.rstrip('\n'))
-                two = two.strip()
-                name, rest = two.split('--', 1)
-                assert name.strip() == base
-                description = rest.strip()
-            yield (
-                os.path.join('man', section, base),
-                base,
-                description,
-                '',
-                section,
-                )
-
-man_pages = list(_get_manpages())
-
 top_level = os.path.dirname(
     os.path.dirname(
         os.path.abspath(__file__)

man/Makefile.am

@@ -9,3 +9,18 @@ endif
 if ENABLE_SERVER
 include Makefile-server.am
 endif
+
+check-local:
+	sphinx-build -b man -d doctrees . $(top_builddir)/man
+
+# prevent `make` from running in parallel, sphinx runs better in batch mode.
+.PHONY: sphinx-build.stamp
+
+$(dist_man_MANS): sphinx-build.stamp
+
+sphinx-build.stamp:
+	sphinx-build -Q -b man -d doctrees -c . . $(top_builddir)/man
+
+clean-local:
+	@rm -f *.8
+	@rm -rf doctrees

man/conf.py

@@ -0,0 +1,42 @@
+import os
+
+project = u'Ceph'
+copyright = u'2010-2014, Inktank Storage, Inc. and contributors. Licensed under Creative Commons BY-SA'
+version = 'dev'
+release = 'dev'
+
+exclude_patterns = ['**/.#*', '**/*~']
+
+def _get_manpages():
+    import os
+    man_dir = os.path.dirname(__file__)
+    sections = os.listdir(man_dir)
+    for section in sections:
+        section_dir = os.path.join(man_dir, section)
+        if not os.path.isdir(section_dir):
+            continue
+        for filename in os.listdir(section_dir):
+            base, ext = os.path.splitext(filename)
+            if ext != '.rst':
+                continue
+            if base == 'index':
+                continue
+            with file(os.path.join(section_dir, filename)) as f:
+                one = f.readline()
+                two = f.readline()
+                three = f.readline()
+                assert one == three
+                assert all(c=='=' for c in one.rstrip('\n'))
+                two = two.strip()
+                name, rest = two.split('--', 1)
+                assert name.strip() == base
+                description = rest.strip()
+            yield (
+                os.path.join(section, base),
+                base,
+                description,
+                '',
+                section,
+                )
+
+man_pages = list(_get_manpages())