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 <[email protected]>
heyingstar · Mar 24, 2015 · 301fe6c · 301fe6c
1 parent 8dd9f6a
commit 301fe6c
Show file tree

Hide file tree

Showing 37 changed files with 64 additions and 37 deletions.
diff --git a/ceph.spec.in b/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

diff --git a/configure.ac b/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])

diff --git a/debian/control b/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,

diff --git a/doc/conf.py b/doc/conf.py
@@ -32,43 +32,6 @@
     ]
 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__)

diff --git a/doc/man/8/ceph-authtool.rst → man/8/ceph-authtool.rst b/doc/man/8/ceph-authtool.rst → man/8/ceph-authtool.rst
diff --git a/doc/man/8/ceph-clsinfo.rst → man/8/ceph-clsinfo.rst b/doc/man/8/ceph-clsinfo.rst → man/8/ceph-clsinfo.rst
diff --git a/doc/man/8/ceph-conf.rst → man/8/ceph-conf.rst b/doc/man/8/ceph-conf.rst → man/8/ceph-conf.rst
diff --git a/doc/man/8/ceph-debugpack.rst → man/8/ceph-debugpack.rst b/doc/man/8/ceph-debugpack.rst → man/8/ceph-debugpack.rst
diff --git a/doc/man/8/ceph-dencoder.rst → man/8/ceph-dencoder.rst b/doc/man/8/ceph-dencoder.rst → man/8/ceph-dencoder.rst
diff --git a/doc/man/8/ceph-deploy.rst → man/8/ceph-deploy.rst b/doc/man/8/ceph-deploy.rst → man/8/ceph-deploy.rst
diff --git a/doc/man/8/ceph-disk.rst → man/8/ceph-disk.rst b/doc/man/8/ceph-disk.rst → man/8/ceph-disk.rst
diff --git a/doc/man/8/ceph-fuse.rst → man/8/ceph-fuse.rst b/doc/man/8/ceph-fuse.rst → man/8/ceph-fuse.rst
diff --git a/doc/man/8/ceph-mds.rst → man/8/ceph-mds.rst b/doc/man/8/ceph-mds.rst → man/8/ceph-mds.rst
diff --git a/doc/man/8/ceph-mon.rst → man/8/ceph-mon.rst b/doc/man/8/ceph-mon.rst → man/8/ceph-mon.rst
diff --git a/doc/man/8/ceph-osd.rst → man/8/ceph-osd.rst b/doc/man/8/ceph-osd.rst → man/8/ceph-osd.rst
diff --git a/doc/man/8/ceph-post-file.rst → man/8/ceph-post-file.rst b/doc/man/8/ceph-post-file.rst → man/8/ceph-post-file.rst
diff --git a/doc/man/8/ceph-rbdnamer.rst → man/8/ceph-rbdnamer.rst b/doc/man/8/ceph-rbdnamer.rst → man/8/ceph-rbdnamer.rst
diff --git a/doc/man/8/ceph-rest-api.rst → man/8/ceph-rest-api.rst b/doc/man/8/ceph-rest-api.rst → man/8/ceph-rest-api.rst
diff --git a/doc/man/8/ceph-run.rst → man/8/ceph-run.rst b/doc/man/8/ceph-run.rst → man/8/ceph-run.rst
diff --git a/doc/man/8/ceph-syn.rst → man/8/ceph-syn.rst b/doc/man/8/ceph-syn.rst → man/8/ceph-syn.rst
diff --git a/doc/man/8/ceph.rst → man/8/ceph.rst b/doc/man/8/ceph.rst → man/8/ceph.rst
diff --git a/doc/man/8/cephfs.rst → man/8/cephfs.rst b/doc/man/8/cephfs.rst → man/8/cephfs.rst
diff --git a/doc/man/8/crushtool.rst → man/8/crushtool.rst b/doc/man/8/crushtool.rst → man/8/crushtool.rst
diff --git a/doc/man/8/librados-config.rst → man/8/librados-config.rst b/doc/man/8/librados-config.rst → man/8/librados-config.rst
diff --git a/doc/man/8/monmaptool.rst → man/8/monmaptool.rst b/doc/man/8/monmaptool.rst → man/8/monmaptool.rst
diff --git a/doc/man/8/mount.ceph.rst → man/8/mount.ceph.rst b/doc/man/8/mount.ceph.rst → man/8/mount.ceph.rst
diff --git a/doc/man/8/osdmaptool.rst → man/8/osdmaptool.rst b/doc/man/8/osdmaptool.rst → man/8/osdmaptool.rst
diff --git a/doc/man/8/rados.rst → man/8/rados.rst b/doc/man/8/rados.rst → man/8/rados.rst
diff --git a/doc/man/8/radosgw-admin.rst → man/8/radosgw-admin.rst b/doc/man/8/radosgw-admin.rst → man/8/radosgw-admin.rst
diff --git a/doc/man/8/radosgw.rst → man/8/radosgw.rst b/doc/man/8/radosgw.rst → man/8/radosgw.rst
diff --git a/doc/man/8/rbd-fuse.rst → man/8/rbd-fuse.rst b/doc/man/8/rbd-fuse.rst → man/8/rbd-fuse.rst
diff --git a/doc/man/8/rbd-replay-many.rst → man/8/rbd-replay-many.rst b/doc/man/8/rbd-replay-many.rst → man/8/rbd-replay-many.rst
diff --git a/doc/man/8/rbd-replay-prep.rst → man/8/rbd-replay-prep.rst b/doc/man/8/rbd-replay-prep.rst → man/8/rbd-replay-prep.rst
diff --git a/doc/man/8/rbd-replay.rst → man/8/rbd-replay.rst b/doc/man/8/rbd-replay.rst → man/8/rbd-replay.rst
diff --git a/doc/man/8/rbd.rst → man/8/rbd.rst b/doc/man/8/rbd.rst → man/8/rbd.rst
diff --git a/man/Makefile.am b/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
diff --git a/man/conf.py b/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())