From nobody Tue Nov 26 11:48:05 2024 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of redhat.com designates 207.211.31.120 as permitted sender) client-ip=207.211.31.120; envelope-from=libvir-list-bounces@redhat.com; helo=us-smtp-1.mimecast.com; Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 207.211.31.120 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass(p=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1575643926; cv=none; d=zohomail.com; s=zohoarc; b=QIWxIxLXRfLCz4EN+qh17FztxsODXV2ohAT34ymwiWO8WFi1OgSlZHYro5uu34OXp5kaWM0yEHVXfNVunhGr9vRIaFMurhiJlw6UFUY/jyxYmhYHVlYPfkp05JLKociKE+YGB6wK9RiXlsLKEkwxaLbx5LsVGe3+J/w6R+M4meE= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1575643926; h=Content-Type:Content-Transfer-Encoding:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To; bh=n6VeX5/qw4PzF7Dc00vpN+72GMaDpnpPeYtczkvvUFw=; b=Ea1x4sjcyco5GiaKYZzA5peElM7ePnSMGnI+vkoAF4xrC52kwNSbCM3vUi6Lsyi5CVFPC5VFUqp9m5nuHEpHmM9sK8zv5S+Isl2+P0+Nt7YWu1MOx16O3xtMtfTU9BEOsjVouzNQxwCashvo7jRfYAZKvesPR7iUhjlLju/ENEk= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 207.211.31.120 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass header.from= (p=none dis=none) header.from= Return-Path: Received: from us-smtp-1.mimecast.com (us-smtp-delivery-1.mimecast.com [207.211.31.120]) by mx.zohomail.com with SMTPS id 1575643926507384.6779742523569; Fri, 6 Dec 2019 06:52:06 -0800 (PST) Received: from mimecast-mx01.redhat.com (mimecast-mx01.redhat.com [209.132.183.4]) (Using TLS) by relay.mimecast.com with ESMTP id us-mta-313-SOTC1YYONjmzgKz6Nf6hiQ-1; Fri, 06 Dec 2019 09:51:19 -0500 Received: from smtp.corp.redhat.com (int-mx02.intmail.prod.int.phx2.redhat.com [10.5.11.12]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx01.redhat.com (Postfix) with ESMTPS id 72D8E107ACC4; Fri, 6 Dec 2019 14:51:13 +0000 (UTC) Received: from colo-mx.corp.redhat.com (colo-mx02.intmail.prod.int.phx2.redhat.com [10.5.11.21]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 489066CE40; Fri, 6 Dec 2019 14:51:13 +0000 (UTC) Received: from lists01.pubmisc.prod.ext.phx2.redhat.com (lists01.pubmisc.prod.ext.phx2.redhat.com [10.5.19.33]) by colo-mx.corp.redhat.com (Postfix) with ESMTP id 0A1EA6B4B3; Fri, 6 Dec 2019 14:51:13 +0000 (UTC) Received: from smtp.corp.redhat.com (int-mx04.intmail.prod.int.phx2.redhat.com [10.5.11.14]) by lists01.pubmisc.prod.ext.phx2.redhat.com (8.13.8/8.13.8) with ESMTP id xB6Ep09r016982 for ; Fri, 6 Dec 2019 09:51:00 -0500 Received: by smtp.corp.redhat.com (Postfix) id B07825DA60; Fri, 6 Dec 2019 14:51:00 +0000 (UTC) Received: from localhost.localdomain.com (ovpn-112-49.ams2.redhat.com [10.36.112.49]) by smtp.corp.redhat.com (Postfix) with ESMTP id 197EA5D9E2; Fri, 6 Dec 2019 14:50:52 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1575643925; h=from:from:sender:sender:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc:mime-version:mime-version: content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references:list-id:list-help: list-unsubscribe:list-subscribe:list-post; bh=n6VeX5/qw4PzF7Dc00vpN+72GMaDpnpPeYtczkvvUFw=; b=d9buHWgywAfYaf6FPT7+BPjRKZCAt8SXb8zsIDjZUDviijGwMfjp/T1+/lP/LSUzpu8odv eCdGij3vaKevTS4lwpdbqIjAwXJ3S/hNMUQGjzqDue76pO7DDyXTM6L4V428QWpG66CIsh Q0FkgHvoyvI0aCO+Fsdf/GRvnqbwZME= From: =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= To: libvir-list@redhat.com Date: Fri, 6 Dec 2019 14:50:29 +0000 Message-Id: <20191206145042.3777845-5-berrange@redhat.com> In-Reply-To: <20191206145042.3777845-1-berrange@redhat.com> References: <20191206145042.3777845-1-berrange@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.79 on 10.5.11.14 X-loop: libvir-list@redhat.com Subject: [libvirt] [PATCH 04/17] docs: introduce rst2man as a mandatory tool for building docs X-BeenThere: libvir-list@redhat.com X-Mailman-Version: 2.1.12 Precedence: junk List-Id: Development discussions about the libvirt library & tools List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: libvir-list-bounces@redhat.com Errors-To: libvir-list-bounces@redhat.com X-Scanned-By: MIMEDefang 2.79 on 10.5.11.12 X-MC-Unique: SOTC1YYONjmzgKz6Nf6hiQ-1 X-Mimecast-Spam-Score: 0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable X-ZohoMail-DKIM: pass (identity @redhat.com) The rst2man tool is provided by python docutils, and as the name suggests, it converts RST documents into man pages. The intention is that our current POD docs will be converted to RST format, allowing one more use of Perl to be eliminated from libvirt. The manual pages will now all be kept in the docs/manpages/ directory, which enables us to include the man pages in the published website. This is good for people searching for libvirt man pages online as it makes it more likely google will send them to the libvirt.org instead of some random third party man page site with outdated content. Signed-off-by: Daniel P. Berrang=C3=A9 --- docs/Makefile.am | 60 ++++++++++++++++++++++++++++++++++++ docs/docs.html.in | 3 ++ docs/manpages/index.rst | 3 ++ m4/virt-external-programs.m4 | 5 +++ 4 files changed, 71 insertions(+) create mode 100644 docs/manpages/index.rst diff --git a/docs/Makefile.am b/docs/Makefile.am index 5f5dce28eb..34fea87805 100644 --- a/docs/Makefile.am +++ b/docs/Makefile.am @@ -197,6 +197,54 @@ kbase_html =3D \ kbasedir =3D $(HTML_DIR)/kbase kbase_DATA =3D $(kbase_html) =20 +manpages_rst =3D \ + manpages/index.rst \ + $(NULL) +manpages1_rst =3D \ + $(NULL) +manpages7_rst =3D \ + $(NULL) +manpages8_rst =3D \ + $(NULL) +manpages_rst +=3D \ + $(manpages1_rst) \ + $(manpages7_rst) \ + $(manpages8_rst) \ + $(NULL) +manpages_rst_html_in =3D \ + $(manpages_rst:%.rst=3D%.html.in) +manpages_html =3D \ + $(manpages_rst_html_in:%.html.in=3D%.html) + +man1_MANS =3D $(manpages1_rst:%.rst=3D%.1) +man7_MANS =3D $(manpages7_rst:%.rst=3D%.7) +man8_MANS =3D $(manpages8_rst:%.rst=3D%.8) + +%.1: %.rst + $(AM_V_GEN)$(MKDIR_P) `dirname $@` && \ + grep -v '^\.\. contents::' < $< | \ + sed -e 's|SYSCONFDIR|$(sysconfdir)|g' \ + -e 's|RUNSTATEDIR|$(runstatedir)|g' | \ + $(RST2MAN) > $@ + +%.7: %.rst + $(AM_V_GEN)$(MKDIR_P) `dirname $@` && \ + grep -v '^\.\. contents::' < $< | \ + sed -e 's|SYSCONFDIR|$(sysconfdir)|g' \ + -e 's|RUNSTATEDIR|$(runstatedir)|g' | \ + $(RST2MAN) > $@ + +%.8: %.rst + $(AM_V_GEN)$(MKDIR_P) `dirname $@` && \ + grep -v '^\.\. contents::' < $< | \ + sed -e 's|SYSCONFDIR|$(sysconfdir)|g' \ + -e 's|RUNSTATEDIR|$(runstatedir)|g' | \ + $(RST2MAN) > $@ + + +manpagesdir =3D $(HTML_DIR)/manpages +manpages_DATA =3D $(manpages_html) + # Generate hvsupport.html and news.html first, since they take one extra s= tep. dot_html_generated_in =3D \ hvsupport.html.in \ @@ -244,6 +292,7 @@ EXTRA_DIST=3D \ $(javascript) $(logofiles) \ $(internals_html_in) $(internals_rst) $(fonts) \ $(kbase_html_in) $(kbase_rst) \ + $(manpages_rst) \ aclperms.htmlinc \ hvsupport.pl \ $(schema_DATA) @@ -262,6 +311,10 @@ CLEANFILES =3D \ $(apilxchtml) \ $(internals_html) \ $(kbase_html) \ + $(manpages_html) \ + $(man1_MANS) \ + $(man7_MANS) \ + $(man8_MANS) \ $(api_DATA) \ $(dot_html_generated_in) \ aclperms.htmlinc @@ -298,6 +351,13 @@ EXTRA_DIST +=3D \ %.png: %.fig convert -rotate 90 $< $@ =20 +manpages/%.html.in: manpages/%.rst + $(AM_V_GEN)$(MKDIR_P) `dirname $@` && \ + grep -v '^:Manual ' < $< | \ + sed -e 's|SYSCONFDIR|$(sysconfdir)|g' \ + -e 's|RUNSTATEDIR|$(runstatedir)|g' | \ + $(RST2HTML) > $@ + %.html.in: %.rst $(AM_V_GEN)$(MKDIR_P) `dirname $@` && \ $(RST2HTML) $< > $@ diff --git a/docs/docs.html.in b/docs/docs.html.in index f441769617..fbf35234d4 100644 --- a/docs/docs.html.in +++ b/docs/docs.html.in @@ -9,6 +9,9 @@
Applications
Applications known to use libvirt
=20 +
Manual pages
+
Manual pages for libvirt tools / daemons
+
Windows
Downloads for Windows
=20 diff --git a/docs/manpages/index.rst b/docs/manpages/index.rst new file mode 100644 index 0000000000..11c72135e8 --- /dev/null +++ b/docs/manpages/index.rst @@ -0,0 +1,3 @@ +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D +Libvirt Manual Pages +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D diff --git a/m4/virt-external-programs.m4 b/m4/virt-external-programs.m4 index ed634a4c73..9b128382fa 100644 --- a/m4/virt-external-programs.m4 +++ b/m4/virt-external-programs.m4 @@ -38,6 +38,11 @@ AC_DEFUN([LIBVIRT_CHECK_EXTERNAL_PROGRAMS], [ then AC_MSG_ERROR("rst2html is required to build libvirt") fi + AC_PATH_PROGS([RST2MAN], [rst2man rst2man.py rst2man-3], []) + if test -z "$RST2MAN" + then + AC_MSG_ERROR("rst2man is required to build libvirt") + fi AC_PATH_PROG([AUGPARSE], [augparse], [/usr/bin/augparse]) AC_PROG_MKDIR_P AC_PROG_LN_S --=20 2.23.0 -- libvir-list mailing list libvir-list@redhat.com https://www.redhat.com/mailman/listinfo/libvir-list