almalinux/lorax
13
0
Fork 0
Code Issues Pull Requests Releases Activity

Use Sphinx to generate manpages

Browse Source 
Use make -C docs man to regenerate the manpages in docs/man/
This commit is contained in:
Brian C. Lane 2016-03-18 16:27:47 -07:00
parent 12690a0aa3
commit e12f6b8ede
9 changed files with 1345 additions and 351 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
Makefile
View File

@ -18,8 +18,8 @@ all: src/pylorax/version.py
install: all
$(PYTHON) setup.py install --root=$(DESTDIR)
mkdir -p $(DESTDIR)/$(mandir)/man1
install -m 644 docs/lorax.1 $(DESTDIR)/$(mandir)/man1
install -m 644 docs/livemedia-creator.1 $(DESTDIR)/$(mandir)/man1
install -m 644 docs/man/lorax.1 $(DESTDIR)/$(mandir)/man1
install -m 644 docs/man/livemedia-creator.1 $(DESTDIR)/$(mandir)/man1
check:
@echo "*** Running pylint ***"

4
docs/conf.py
View File

@ -243,8 +243,8 @@ latex_documents = [
# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
man_pages = [
('index', 'Lorax', u'Lorax Documentation',
[u'Anaconda Team'], 1)
('lorax', 'lorax', u'Lorax Documentation', [u'Anaconda Team'], 1),
('livemedia-creator', 'livemedia-creator', u'Live Media Creator Documentation', [u'Anaconda Team'], 1)
]
# If true, show URL addresses after external links.

251
docs/livemedia-creator.1
View File

@ -1,251 +0,0 @@
.TH LIVEMEDIA-CREATOR 1 2014\-04\-03
.SH NAME
livemedia-creator \- Create live install media
.SH SYNOPSIS
livemedia-creator [-h]
(--make-iso | --make-disk | --make-fsimage | --make-appliance | --make-ami | --make-tar | --make-pxe-live | --make-ostree-live)
[--iso ISO] [--iso-only] [--disk-image DISK_IMAGE]
[--fs-image FS_IMAGE] [--ks KS]
[--image-name IMAGE_NAME] [--image-only]
[--fs-label FS_LABEL]
[--image-type IMAGE_TYPE] [--qemu-arg QEMU_ARGS]
[--compression] [--compress-arg]
[--live-rootfs-size LIVE_ROOTFS_SIZE]
[--live-rootfs-keep-size LIVE_ROOTFS_KEEP_SIZE]
[--keep-image] [--no-virt] [--proxy PROXY]
[--anaconda-arg ANACONDA_ARGS]
[--armplatform ARMPLATFORM] [--location LOCATION]
[--logfile LOGFILE]
[--lorax-templates LORAX_TEMPLATES] [--tmp TMP]
[--resultdir RESULT_DIR] [--app-name APP_NAME]
[--app-template APP_TEMPLATE] [--app-file APP_FILE]
[--ram MEMORY] [--vcpus VCPUS] [--vnc VNC]
[--arch ARCH] [--kernel-args KERNEL_ARGS]
[--dracut-arg DRACUT_ARGS] [--title TITLE]
[--project PROJECT] [--releasever RELEASEVER]
[--volid VOLID] [--squashfs_args SQUASHFS_ARGS]
[--timeout TIMEOUT]
.SH DESCRIPTION
livemedia-creator uses Anaconda, kickstart and Lorax to create bootable media
that use the same install path as a normal system install. It can be used to
make live isos, bootable (partitioned) disk images and filesystem images for
use with virtualization.
The general idea is to use virt-install to install into a disk image and then
use the disk image to create the bootable media.
livemedia-creator --help will describe all of the options available. To create a
bootable iso you need at least:
--make-iso to create a final bootable .iso
--iso to specify the Anaconda install media to use with virt-install
--ks is the kickstart to use to install the system
.SH OPTIONAL ARGUMENTS:
.TP
\fB\-h, \-\-help\fR
show this help message and exit
.TP
\fB\-\-make\-iso\fR
Build a live iso
.TP
\fB\-\-make\-disk\fR
Build a partitioned disk image
.TP
\fB\-\-make\-fsimage\fR
Build a filesystem image
.TP
\fB\-\-make\-appliance\fR
Build an appliance image and XML description
.TP
\fB\-\-make\-ami\fR
Build an ami image
.TP
\fB\-\-make\-tar\fR
Build a tar of the root filesystem. Defaults to root.tar.xz
.TP
\fB\-\-make\-pxe\-live\fR
Build a live pxe boot squashfs image
.TP
\fB\-\-make\-ostree\-live\fR
Build a live pxe boot squashfs image of Atomic Host
.TP
\fB\-\-iso ISO\fR
Anaconda installation .iso path to use for virt-install
.TP
\fB\-\-iso-only\fR
Remove all iso creation artifacts except the boot.iso, combine with --iso-name to rename the boot.iso
.TP
\fB\-\-disk\-image DISK_IMAGE\fR
Path to disk image to use for creating final image
.TP
\fB\-\-fs\-image FS_IMAGE\fR
Path to existing filesystem image to use for creating final image.
.TP
\fB\-\-image-type IMAGE_TYPE\fR
Create a qemu-img image instead of raw sparse image when making disk images. See qemu-img --help for a list of supported types.
.TP
\fB\-\-qemu\-arg\fR
Arguments to pass to qemu-img. Pass once for each argument
.TP
\fB\-\-compress\fR
Compression binary for make-tar. xz, lzma, gzip, and bzip2 are supported. xz is the default.
.TP
\fB\-\-compress\-arg\fR
Arguments to pass to compression. Pass once for each argument
.TP
\fB\-\-ks KS\fR
Kickstart file defining the install.
.TP
\fB\-\-image\-name IMAGE_NAME\fR
Name of fs/disk image to create. Default is a random name.
.TP
\fB\-\-fs\-label FS_LABEL\fR
Label to set on fsimage, default is 'Anaconda'
.TP
\fB\-\-image\-only\fR
Exit after creating fs/disk image.
.TP
\fB\-\-keep\-image\fR
Keep raw disk image after .iso creation
.TP
\fB\-\-no\-virt\fR
Use Anaconda's image install instead of virt-install
.TP
\fB\-\-proxy PROXY\fR
proxy URL to use for the install
.TP
\fB\-\-anaconda\-arg ANACONDA_ARGS\fR
Additional argument to pass to anaconda (no-virt mode). Pass once for eachargument
.TP
\fB\-\-armplatform ARMPLATFORM\fR
the platform to use when creating images for ARM, i.e., highbank, mvebu, omap,tegra, etc.
.TP
\fB\-\-location LOCATION\fR
location of iso directory tree with initrd.img and vmlinuz. Used to run virt-install with a newer initrd than the iso.
.TP
\fB\-\-logfile LOGFILE\fR
Path to logfile
.TP
\fB\-\-lorax\-templates LORAX_TEMPLATES\fR
Path to mako templates for lorax
.TP
\fB\-\-tmp TMP\fR
Top level temporary directory
.TP
\fB\-\-resultdir RESULT_DIR\fR
Directory to copy the resulting images and iso into. Defaults to the temporaryworking directory
.TP
\fB\-\-title TITLE\fR
Substituted for @TITLE@ in bootloader config files
.TP
\fB\-\-project PROJECT\fR
substituted for @PROJECT@ in bootloader config files
.TP
\fB\-\-releasever RELEASEVER\fR
substituted for @VERSION@ in bootloader config files
.TP
\fB\-\-volid VOLID\fR
volume id
.TP
\fB\-\-squashfs_args SQUASHFS_ARGS\fR
additional squashfs args
.TP
\fB\-\-timeout TIMEOUT\fR
Cancel installer after X minutes
.SH APPLIANCE ARGUMENTS:
.TP
\fB\-\-app\-name APP_NAME\fR
Name of appliance to pass to template
.TP
\fB\-\-app\-template APP_TEMPLATE\fR
Path to template to use for appliance data.
.TP
\fB\-\-app\-file APP_FILE\fR
Appliance template results file.
.SH PXE\-LIVE ARGUMENTS:
.TP
\fB\-\-live\-rootfs\-size\fR
Size of root filesystem of live image in GiB. By default approximate size of space used in root filesystem is used.
.TP
\fB\-\-live\-rootfs\-keep\-size\fR
Keep the size of original root filesystem (rounded down to GiB) in live image
.SH VIRT\-INSTALL ARGUMENTS:
.TP
\fB\-\-ram MEMORY\fR
Memory to allocate for installer in megabytes.
.TP
\fB\-\-vcpus VCPUS\fR
Passed to --vcpus command
.TP
\fB\-\-vnc VNC\fR
Passed to qemu -display command. eg. vnc=127.0.0.1:5, default is to choose the first unused vnc port.
.TP
\fB\-\-arch ARCH\fR
Passed to --arch command
.TP
\fB\-\-kernel\-args KERNEL_ARGS\fR
Additional argument to pass to the installation kernel
.SH DRACUT ARGUMENTS:
.TP
\fB\-\-dracut\-arg DRACUT_ARGS\fR
Argument to pass to dracut when rebuilding the initramfs. Pass this once foreach argument. NOTE: this overrides the default.
.SH "SEE ALSO"
Documentation in /usr/share/doc/lorax/README.livemedia-creator
.SH AUTHOR
.nf
Brian C. Lane
.fi

5
docs/livemedia-creator.rst
View File

@ -39,8 +39,11 @@ Conventions used in this document:
``image`` is the disk image being created by running livemedia-creator
livemedia-creator cmdline arguments
-----------------------------------
.. argparse::
:ref: livemedia-creator.get_parser
:ref: pylorax.cmdline.lmc_parser
:prog: livemedia-creator

94
docs/lorax.1
View File

@ -1,94 +0,0 @@
.TH LORAX 1 2013\-07\-26
.SH NAME
lorax \- Create installer boot iso
.SH SYNOPSIS
lorax -p PRODUCT -v VERSION -r RELEASE -s REPOSITORY OUTPUTDIR
.SH DESCRIPTION
lorax is used to create the installer boot iso.
.SH OPTIONS
.TP
\fB\-h, \-\-help\fR
show this help message and exit
.TP
\fB\-V\fR
show program's version number and exit
.SH REQUIRED ARGUMENTS:
.TP
\fB\-p STRING, \-\-product=STRING\fR
product name
.TP
\fB\-v STRING, \-\-version=STRING\fR
version identifier
.TP
\fB\-r STRING, \-\-release=STRING\fR
release information
.TP
\fB\-s REPOSITORY, \-\-source=REPOSITORY\fR
source repository (may be listed multiple times)
.SH
OPTIONAL ARGUMENTS:
.TP
\fB\-m REPOSITORY, \-\-mirrorlist=REPOSITORY\fR
mirrorlist repository (may be listed multiple times)
.TP
\fB\-t STRING, \-\-variant=STRING\fR
variant name
.TP
\fB\-b URL, \-\-bugurl=URL\fR
bug reporting URL for the product
.TP
\fB\-\-isfinal\fR
.TP
\fB\-c STRING, \-\-config=STRING\fR
config file
.TP
\fB\-\-proxy=STRING\fR
repo proxy url:port
.TP
\fB\-e STRING, \-\-excludepkgs=STRING\fR
package glob to exclude (may be listed multiple times)
.TP
\fB\-\-buildarch=STRING\fR
build architecture
.TP
\fB\-\-volid=STRING\fR
volume id
.TP
\fB\-\-nomacboot\fR
.TP
\fB\-\-logfile=LOGFILE\fR
Path to logfile
.TP
\fB\-\-tmp=TMP\fR
Top level temporary directory
.SH AUTHORS
.nf
Martin Gracik
Will Woods
Brian C. Lane
.fi

5
docs/lorax.rst
View File

@ -16,8 +16,11 @@ rawhide version to build the boot.iso for rawhide, along with the rawhide
repositories.
lorax cmdline arguments
-----------------------
.. argparse::
:ref: lorax.get_parser
:ref: pylorax.cmdline.lorax_parser
:prog: lorax

1020
docs/man/livemedia-creator.1 Normal file
View File

File diff suppressed because it is too large Load Diff

305
docs/man/lorax.1 Normal file
View File

@ -0,0 +1,305 @@
.\" Man page generated from reStructuredText.
.
.TH "LORAX" "1" "March 18, 2016" "25.2" "Lorax"
.SH NAME
lorax \- Lorax Documentation
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.INDENT 0.0
.TP
.B Authors
Brian C. Lane <\fI\%bcl@redhat.com\fP>
.UNINDENT
.sp
"I am the Lorax. I speak for the trees [and images]."
.sp
The \fI\%lorax\fP tool is used to create the
\fI\%Anaconda\fP installer boot.iso as
well as the basic release tree, and .treeinfo metadata file. Its dependencies
are fairly light\-weight because it needs to be able to run in a mock chroot
environment. It is best to run lorax from the same release as is being targeted
because the templates may have release specific logic in them. eg. Use the
rawhide version to build the boot.iso for rawhide, along with the rawhide
repositories.
.SH LORAX CMDLINE ARGUMENTS
.sp
Create the Anaconda boot.iso
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
usage: lorax [\-h] \-p PRODUCT \-v VERSION \-r RELEASE [\-s REPOSITORY]
[\-\-repo REPOSITORY] [\-m REPOSITORY] [\-t VARIANT] [\-b URL]
[\-\-isfinal] [\-c CONFIGFILE] [\-\-proxy HOST] [\-i PACKAGE]
[\-\-buildarch ARCH] [\-\-volid VOLID] [\-\-macboot] [\-\-nomacboot]
[\-\-noupgrade] [\-\-logfile LOGFILE] [\-\-tmp TMP]
[\-\-cachedir CACHEDIR] [\-\-workdir WORKDIR] [\-\-force]
[\-\-add\-template ADD_TEMPLATES]
[\-\-add\-template\-var ADD_TEMPLATE_VARS]
[\-\-add\-arch\-template ADD_ARCH_TEMPLATES]
[\-\-add\-arch\-template\-var ADD_ARCH_TEMPLATE_VARS] [\-\-noverify]
[\-\-sharedir SHAREDIR] [\-\-enablerepo [repo]]
[\-\-disablerepo [repo]] [\-V]
OUTPUTDIR
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B Positional arguments:
.INDENT 7.0
.TP
.Boutputdir
Output directory
.UNINDENT
.TP
.B Options:
.INDENT 7.0
.TP
.B \-p\fP,\fB \-\-product
product name
.TP
.B \-v\fP,\fB \-\-version
version identifier
.TP
.B \-r\fP,\fB \-\-release
release information
.TP
.B \-s=[]\fP,\fB \-\-source=[]
source repository (may be listed multiple times)
.TP
.B \-\-repo=[]
source dnf repository file
.TP
.B \-m=[]\fP,\fB \-\-mirrorlist=[]
mirrorlist repository (may be listed multiple times)
.TP
.B \-t\fP,\fB \-\-variant
variant name
.TP
.B \-b=your distribution provided bug reporting tool\fP,\fB \-\-bugurl=your distribution provided bug reporting tool
bug reporting URL for the product
.TP
.B \-\-isfinal=False
Undocumented
.TP
.B \-c=/etc/lorax/lorax.conf\fP,\fB \-\-config=/etc/lorax/lorax.conf
config file
.TP
.B \-\-proxy
repo proxy url:port
.TP
.B \-i=[]\fP,\fB \-\-installpkgs=[]
package glob to install before runtime\-install.tmpl runs. (may be listed multiple times)
.TP
.B \-\-buildarch
build architecture
.TP
.B \-\-volid
volume id
.TP
.B \-\-macboot=True
Undocumented
.TP
.B \-\-nomacboot=True
Undocumented
.TP
.B \-\-noupgrade=True
Undocumented
.TP
.B \-\-logfile=./lorax.log
Path to logfile
.TP
.B \-\-tmp=/var/tmp
Top level temporary directory
.TP
.B \-\-cachedir
DNF cache directory. Default is a temporary dir.
.TP
.B \-\-workdir
Work directory, overrides \-\-tmp. Default is a temporary dir under /var/tmp
.TP
.B \-\-force=False
Run even when the destination directory exists
.TP
.B \-\-add\-template=[]
Additional template for runtime image
.TP
.B \-\-add\-template\-var=[]
Set variable for runtime image template
.TP
.B \-\-add\-arch\-template=[]
Additional template for architecture\-specific image
.TP
.B \-\-add\-arch\-template\-var=[]
Set variable for architecture\-specific image
.TP
.B \-\-noverify=True
Do not verify the install root
.TP
.B \-\-sharedir
Directory containing all the templates. Overrides config file sharedir
.TP
.B \-\-enablerepo=[]
Names of repos to enable
.TP
.B \-\-disablerepo=[]
Names of repos to disable
.TP
.B \-V
show program\(aqs version number and exit
.UNINDENT
.UNINDENT
.SH QUICKSTART
.sp
Run this as root to create a boot.iso in \fB\&./results/\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
dnf install lorax
setenforce 0
lorax \-p Fedora \-v 23 \-r 23 \e
\-s http://dl.fedoraproject.org/pub/fedora/linux/releases/23/Everything/x86_64/os/ \e
\-s http://dl.fedoraproject.org/pub/fedora/linux/updates/23/x86_64/ \e
\&./results/
setenforce 1
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
You can add your own repos with \fB\-s\fP and packages with higher NVRs will
override the ones in the distribution repositories.
.sp
Under \fB\&./results/\fP will be the release tree files: .discinfo, .treeinfo, everything that
goes onto the boot.iso, the pxeboot directory, and the boot.iso under \fB\&./images/\fP\&.
.SH HOW IT WORKS
.sp
Lorax uses \fI\%dnf\fP to install
packages into a temporary directory, sets up configuration files, it then
removes unneeded files to save space, and creates a squashfs filesystem of the
files. The iso is then built using a generic initramfs and the kernel from the
selected repositories.
.sp
To drive these processes Lorax uses a custom template system, based on \fI\%Mako
templates\fP with the addition of custom
commands (documented in \fBpylorax.ltmpl.LoraxTemplateRunner\fP). Mako
supports \fB%if/%endif\fP blocks as well as free\-form python code inside \fB<%
%>\fP tags and variable substitution with \fB${}\fP\&. The default templates are
shipped with lorax in \fB/usr/share/lorax/templates.d/99\-generic/\fP and use the
\fB\&.tmpl\fP extension.
.SS runtime\-install.tmpl
.sp
The \fBruntime\-install.tmpl\fP template lists packages to be installed using the
\fBinstallpkg\fP command. This template is fairly simple, installing common packages and
architecture specific packages. It must end with the \fBrun_pkg_transaction\fP
command which tells dnf to download and install the packages.
.SS runtime\-postinstall.tmpl
.sp
The \fBruntime\-postinstall.tmpl\fP template is where the system configuration
happens. The installer environment is similar to a normal running system, but
needs some special handling. Configuration files are setup, systemd is told to
start the anaconda.target instead of a default system target, and a number of
unneeded services are disabled, some of which can interfere with the
installation. A number of template commands are used here:
.INDENT 0.0
.IP \(bu 2
\fBappend\fP to add text to a file.
.IP \(bu 2
\fBchmod\fP changes the file\(aqs mode.
.IP \(bu 2
\fBgconfset\fP runs gconfset.
.IP \(bu 2
\fBinstall\fP to install a file into the installroot.
.IP \(bu 2
\fBmkdir\fP makes a new directory.
.IP \(bu 2
\fBmove\fP to move a file into the installroot
.IP \(bu 2
\fBreplace\fP does text substitution in a file
.IP \(bu 2
\fBremove\fP deletes a file
.IP \(bu 2
\fBruncmd\fP run arbitrary commands.
.IP \(bu 2
\fBsymlink\fP creates a symlink
.IP \(bu 2
\fBsystemctl\fP runs systemctl in the installroot
.UNINDENT
.SS runtime\-cleanup.tmpl
.sp
The \fBruntime\-cleanup.tmpl\fP template is used to remove files that aren\(aqt strictly needed
by the installation environment. In addition to the \fBremove\fP template command it uses:
.INDENT 0.0
.IP \(bu 2
\fBremovepkg\fP
remove all of a specific package\(aqs contents. A package may be pulled in as a dependency, but
not really used. eg. sound support.
.IP \(bu 2
\fBremovefrom\fP
Removes some files from a package. A file glob can be used, or the \-\-allbut option to
remove everything except a select few.
.IP \(bu 2
\fBremovekmod\fP
Removes kernel modules
.UNINDENT
.SS The squashfs filesystem
.sp
After \fBruntime\-*.tmpl\fP templates have finished their work lorax creates an
empty ext4 filesystem, copies the remaining files to it, and makes a squashfs
filesystem of it. This file is the / of the boot.iso\(aqs installer environment
and is what is in the LiveOS/squashfs.img file on the iso.
.SS iso creation
.sp
The iso creation is handled by another set of templates. The one used depends
on the architecture that the iso is being created for. They are also stored in
\fB/usr/share/lorax/templates.d/99\-generic\fP and are named after the arch, like
\fBx86.tmpl\fP and \fBaarch64.tmpl\fP\&. They handle creation of the tree, copying
configuration template files, configuration variable substitution, treeinfo
metadata (via the \fBtreeinfo\fP
template command). Kernel and initrd are copied from the installroot to their
final locations and then mkisofs is run to create the boot.iso
.SH CUSTOM TEMPLATES
.sp
The default set of templates and configuration files from the lorax\-generic\-templates package
are shipped in the \fB/usr/share/lorax/templates.d/99\-generic/\fP directory. You can
make a copy of them and place them into another directory under \fBtemplates.d\fP
and they will be used instead if their sort order is below all other directories. This
allows multiple packages to ship lorax templates without conflict. You can (and probably
should) select the specific template directory by passing \fB\-\-sharedir\fP to lorax.
.SH AUTHOR
Anaconda Team
.SH COPYRIGHT
2015, Red Hat, Inc.
.\" Generated by docutils manpage writer.
.

8
docs/pylorax.rst
View File

@ -20,6 +20,14 @@ pylorax.buildstamp module
:undoc-members:
:show-inheritance:
pylorax.cmdline module
----------------------
.. automodule:: pylorax.cmdline
:members:
:undoc-members:
:show-inheritance:
pylorax.decorators module
-------------------------