Re: [libvirt] [PATCH sandbox v5 15/20] Image: man file for virt-sandbox-image

On Tue, 2015-09-08 at 17:29 +0100, Daniel P. Berrange wrote: > From: Eren Yagdiran <erenyagdiran(a)gmail.com&gt; > > Signed-off-by: Daniel P. Berrange <berrange(a)redhat.com&gt; > --- > bin/Makefile.am | 5 ++ > bin/virt-sandbox-image.pod | 169 +++++++++++++++++++++++++++++++++++++++++++++ > libvirt-sandbox.spec.in | 1 + > 3 files changed, 175 insertions(+) > create mode 100644 bin/virt-sandbox-image.pod > > diff --git a/bin/Makefile.am b/bin/Makefile.am > index deedcf6..398e90c 100644 > --- a/bin/Makefile.am > +++ b/bin/Makefile.am > @@ -20,6 +20,7 @@ POD_FILES = \ > virt-sandbox-service-delete.pod \ > virt-sandbox-service-reload.pod \ > virt-sandbox-service-upgrade.pod \ > + virt-sandbox-image.pod \ > $(NULL) > EXTRA_DIST = $(bin_SCRIPTS) $(POD_FILES) virt-sandbox-service-bash-completion.sh virt-sandbox-service.logrotate > EXTRA_DIST += virt-sandbox-service-bash-completion.sh > @@ -34,6 +35,7 @@ man1_MANS = \ > virt-sandbox-service-delete.1 \ > virt-sandbox-service-reload.1 \ > virt-sandbox-service-upgrade.1 \ > + virt-sandbox-image.1 \ > $(NULL) > > POD2MAN = pod2man -c "Virtualization Support" -r "$(PACKAGE)-$(VERSION)" > @@ -65,6 +67,9 @@ virt-sandbox-service-reload.1: virt-sandbox-service-reload.pod Makefile > virt-sandbox-service-upgrade.1: virt-sandbox-service-upgrade.pod Makefile > $(AM_V_GEN)$(POD2MAN) $< $(srcdir)/$@ > > +virt-sandbox-image.1: virt-sandbox-image.pod Makefile > + $(AM_V_GEN)$(POD2MAN) $< $(srcdir)/$@ > + > CLEANFILES = $(man1_MANS) > > virt_sandbox_SOURCES = virt-sandbox.c > diff --git a/bin/virt-sandbox-image.pod b/bin/virt-sandbox-image.pod > new file mode 100644 > index 0000000..85954b0 > --- /dev/null > +++ b/bin/virt-sandbox-image.pod > @@ -0,0 +1,169 @@ > +=head1 NAME > + > +virt-sandbox-image - Sandbox Container Image Tool > + > +=head1 SYNOPSIS > + > + {download,create,run,delete} > + > + commands: > + > + download Download template data > + > + create Create image from template data > + > + run Run an already built image > + > + delete Delete template data > + > +=head1 DESCRIPTION > + > +virt-sandbox-image.py is a sandbox container image tool developed in python. > +This tool can download,create,run and delete templates which are provided by > +different sources. This tool comes with Docker source by default. Other sources > +can be implemented by extending source class The mention on the default source and possibility to add more may not fit a man page... or we'll need to reword / remove it someday. > +=head1 OPTIONS > + > +=over 4 > + > +=item B<download -s source -r registry -u username -p password -t template_directory template> > + > Again here, do we really want to use the word "registry" sounding too dockerish? > > +Download a template by given name with a specified source. > + > +=over 6 > + > +=item B<template> > + > +Template name to download > + > +=item B<-s or --source> > + > +Source parameter will try load source module under sources/ directory. Each source has to implement Source.py base class and register itself with a proper name > +Default source is Docker. > + Do we really want to include development hints in the man? > +=item B<-r or --registry> > + > +Custom registry url for downloading data. This might need privileged credentials which can be specified by --username and --password parameters. > + > +=item B<-u or --username> > + > +Username for custom registry authentication > + > +=item B<-p or --password> > + > +Password for custom registry authentication > + > +=item B<-t or --template-dir> > + > +Custom directory for downloading template data > + > +=back > + > +=item B<create -s source -c uri -f format template> > + > +Create already downloaded template into image with given format. > + > +=over 5 > + > +=item B<template> > + > +Template name to download. > + > +=item B<format> > + > +Image format e.g qcow2 > + > +=item B<-s or --source> > + > +Source parameter will try load source module under sources/ directory. Each source has to implement Source.py base class and register itself with a proper name > +Default source is Docker. > + > +=item B<-c or --connect> > + > +Driver parameter can be specified with only supported driver by libvirt-sandbox. These are lxc:///, qemu:///session, qemu:///system. > + > +=back > + > +=item B<run -n name -N network -v volume -s source -c uri template command...> > + > +Run already built image. If B<command> is not specified, the default defined > +command for the image will be run. > + > +=over 6 > + > +=item B<template> > + > +Template name to download. > + > +=item B<imagepath> > + > +Image path where template image will be stored. > + > +=item B<-n or --name> > + > +The sandbox guest name > + > +=item B<-N or --network> > + > +Network params will be passed directly to the virt-sandbox. More information about network params, See C<virt-sandbox(8)> > + > +=item B<-v or --volume> > + > +Volume params are for binding host-paths to the guest. E.g -v /home:/home will map /home directory from host to the guest. > + > +=item B<-c or --connect> > + > +Driver parameter can be specified with only supported driver by libvirt-sandbox. These are lxc:///, qemu:///session, qemu:///system. > + > +=back > + > +=item B<delete name imagepath -s source > > + > +Delete downloaded template data and its built image. > + > +=over 3 > + > +=item B<name> > + > +Template name to delete. > + > +=item B<imagepath> > + > +Image path where template data or image stays. > + > +=item B<-s or --source> > + > +Source parameter will try load source module under sources/ directory. Each source has to implement Source.py base class and register itself with a proper name > +Default source is Docker. > + > +=back > + > +=back > + > +=head1 SEE ALSO > + > +C<virt-sandbox(8)> > + > +=head1 FILES > + > +Container content will be stored in subdirectories of > +/var/lib/libvirt/templates, by default. > + > +=head1 AUTHORS > + > +Daniel P. Berrange <dan(a)berrange.com&gt; > + > +Eren Yagdiran <erenyagdiran(a)gmail.com&gt; > + > +=head1 COPYRIGHT > + > +Copyright (C) 2013 Red Hat, Inc. > +Copyright (C) 2015 Universitat Politecnica de Catalunya. > + > +=head1 LICENSE > + > +virt-sandbox-image is distributed under the terms of the GNU LGPL v2+. > +This is free software; see the source for copying conditions. > +There is NO warranty; not even for MERCHANTABILITY or FITNESS > +FOR A PARTICULAR PURPOSE > diff --git a/libvirt-sandbox.spec.in b/libvirt-sandbox.spec.in > index 54fde55..b488cec 100644 > --- a/libvirt-sandbox.spec.in > +++ b/libvirt-sandbox.spec.in > @@ -102,6 +102,7 @@ rm -rf $RPM_BUILD_ROOT > %{_libexecdir}/virt-sandbox-service-util > %{python_sitelib}/libvirt_sandbox > %{_mandir}/man1/virt-sandbox.1* > +%{_mandir}/man1/virt-sandbox-image.1* > %{_mandir}/man1/virt-sandbox-service.1* > %{_mandir}/man1/virt-sandbox-service-*.1* > ACK, but would be good to think about the raised questions before pushing.