Merge lp:~evilnick/maas/man-pages into lp:~maas-committers/maas/trunk

Proposed by Nick Veitch
Status: Merged
Approved by: Nick Veitch
Approved revision: 1333
Merged at revision: 1354
Proposed branch: lp:~evilnick/maas/man-pages
Merge into: lp:~maas-committers/maas/trunk
Diff against target: 186 lines (+96/-55)
5 files modified
docs/conf.py (+4/-0)
docs/man/maas-cli.8.rst (+3/-1)
docs/man/maas-import-pxe-files.8.rst (+48/-0)
docs/man/maas.8.rst (+41/-0)
man/maas-import-pxe-files.8 (+0/-54)
To merge this branch: bzr merge lp:~evilnick/maas/man-pages
Reviewer Review Type Date Requested Status
Gavin Panella (community) Approve
Review via email: mp+134878@code.launchpad.net

Commit message

adds source files for remaining man pages (maas, maas-import-pxe-files)

Description of the change

This is the final part to address bug #975454

It adds sphinx source files for man pages for maas-import-pxe-files and the maas command. These are built by
the 'make man' part of the main makefile and placed into the man directory for installation.

To post a comment you must log in.
Revision history for this message
Gavin Panella (allenap) wrote :

Looks good. I have some more things for bug 975454 so don't close it yet.

review: Approve
Revision history for this message
Nick Veitch (evilnick) wrote :

Cool. okay. Some hints as to what they might be would help :)
I think this bug is pretty much done. That isn't to say I don't have stuff to add to the docs, but in the sense that there is documentation and there are man pages. I think I would prefer specific bugs for other things

Preview Diff

[H/L] Next/Prev Comment, [J/K] Next/Prev File, [N/P] Next/Prev Hunk
1=== modified file 'docs/conf.py'
2--- docs/conf.py 2012-11-08 12:55:51 +0000
3+++ docs/conf.py 2012-11-19 11:55:27 +0000
4@@ -230,6 +230,10 @@
5 # (source start file, name, description, authors, manual section).
6 man_pages = [
7 ('man/maas-cli.8', 'maas-cli', u'MAAS API commandline utility',
8+ [u'Canonical 2012'], 8),
9+ ('man/maas-import-pxe-files.8', 'maas-import-pxe-files', u'MAAS helper script',
10+ [u'Canonical 2012'], 8),
11+ ('man/maas.8', 'maas', u'MAAS administration tool',
12 [u'Canonical 2012'], 8)
13 ]
14
15
16=== modified file 'docs/man/maas-cli.8.rst'
17--- docs/man/maas-cli.8.rst 2012-10-25 13:38:22 +0000
18+++ docs/man/maas-cli.8.rst 2012-11-19 11:55:27 +0000
19@@ -21,6 +21,8 @@
20 ^^^^^^^^^^^^^^^^^^^^^
21 For more documentation of MAAS, please see https://maas.ubuntu.com/docs
22
23-
24+See Also
25+^^^^^^^^
26+`maas`, `maas-import-pxe-files`
27
28
29
30=== added file 'docs/man/maas-import-pxe-files.8.rst'
31--- docs/man/maas-import-pxe-files.8.rst 1970-01-01 00:00:00 +0000
32+++ docs/man/maas-import-pxe-files.8.rst 2012-11-19 11:55:27 +0000
33@@ -0,0 +1,48 @@
34+maas-import-pxe-files
35+---------------------
36+
37+USAGE
38+^^^^^
39+
40+maas-import-pxe-files [-h, --help]
41+
42+DESCRIPTION
43+^^^^^^^^^^^
44+
45+This is a helper script for the MAAS software. It downloads Ubuntu
46+images and organises them for use by MAAS in commissioning nodes.
47+The script is usually run regularly by a cron task, though it
48+needs to be run manually the first time a MAAS system is installed.
49+Images that are already in place are kept unchanged, unless the
50+version in the archive has since been updated.
51+
52+The script reads a configuration file /etc/maas/import_pxe_files in
53+order to determine:
54+
55+**ARCHIVE:** Location of the Ubuntu download archive
56+
57+**RELEASES:** Ubuntu releases to download
58+
59+**ARCHES:** Architectures for which images should be downloaded
60+
61+To support development setups that run directly from a code branch, it will
62+also look for /etc/maas/import_pxe_files relative to the current
63+directory.
64+
65+The script uses `wget` to download the kernel and initrd image for
66+each architecture in ARCHES and each release in RELEASES. In addition it
67+copies the Intel-architecture pre-boot loader `pxelinux.0` (plus some
68+of its modules such as `chain.c32`) from its installed location in
69+/usr/lib/syslinux/.
70+
71+These images are the minimum that's required to start installing a node.
72+During installation, a node may download its packages over the network.
73+
74+
75+Further Documentation
76+^^^^^^^^^^^^^^^^^^^^^
77+For more documentation of MAAS, please see https://maas.ubuntu.com/docs
78+
79+See Also
80+^^^^^^^^
81+`maas`, `maas-cli`
82
83=== added file 'docs/man/maas.8.rst'
84--- docs/man/maas.8.rst 1970-01-01 00:00:00 +0000
85+++ docs/man/maas.8.rst 2012-11-19 11:55:27 +0000
86@@ -0,0 +1,41 @@
87+maas
88+----
89+
90+USAGE
91+^^^^^
92+
93+maas [-h, --help] createsuperuser | changepassword | shell
94+
95+DESCRIPTION
96+^^^^^^^^^^^
97+
98+The `maas` command is part of Canonical's Metal As A Service software. It is
99+derived from and can be used similarly to the `django-admin` command, and must
100+be run with root privileges.
101+
102+For the end user, there are only three subcommands of interest.
103+
104+**createsuperuser**
105+ This subcommand is used to create a superuser for the
106+ MAAS install. The suggested username is "root". This command usually only
107+ needs to be run when installing MAAS for the first time.
108+
109+**changepassword**
110+ This subcommand is used to change the superuser password
111+ for the MAAS install. You will be prompted to enter a new password, and then
112+ enter it once again to verify.
113+
114+**shell**
115+ This subcommand may be useful for debugging installed systems. It
116+ will open a new python shell environment with the correct django environment
117+ for working with the installed MAAS software.
118+
119+
120+Further Documentation
121+^^^^^^^^^^^^^^^^^^^^^
122+For more documentation of MAAS, please see https://maas.ubuntu.com/docs
123+
124+See Also
125+^^^^^^^^
126+`maas-cli`, `maas-import-pxe-files`
127+
128
129=== removed file 'man/maas-import-pxe-files.8'
130--- man/maas-import-pxe-files.8 2012-08-30 13:09:12 +0000
131+++ man/maas-import-pxe-files.8 1970-01-01 00:00:00 +0000
132@@ -1,54 +0,0 @@
133-.TH maas\-import\-pxe-files 8 "16 July 2012" maas "maas"
134-.SH NAME
135-\fBmaas\-import\-pxe-files\fP \- import Ubuntu install images into MAAS
136-
137-.SH DESCRIPTION
138-\fBmaas\-import\-pxe\-files\fP downloads Ubuntu images and installs them into
139-MAAS. The MAAS server needs these images to provides nodes with operating
140-systems. Images that are already in place are kept unchanged, unless the
141-version in the archive has since been updated.
142-
143-The script reads a configuration file \fI/etc/maas/import_pxe_files\fP in
144-order to determine:
145- - ARCHIVE: Location of the Ubuntu download archive
146- - RELEASES: Ubuntu releases to download
147- - ARCHES: Architectures for which images should be downloaded
148-
149-(To support development setups that run directly from a code branch, it will
150-also look for \fIetc/maas/import_pxe_files\fP relative to the current
151-directory).
152-
153-The script uses \fBwget\fP(1) to download the kernel and initrd image for
154-each architecture in ARCHES and each release in RELEASES. In addition it
155-copies the Intel-architecture pre-boot loader \fBpxelinux.0\fP (plus some
156-of its modules such as \fBchain.c32\fP) from its installed location in
157-\fI/usr/lib/syslinux/\fP.
158-
159-These images are the minimum that's required to start installng a node.
160-During installation, a node may download its packages over the network.
161-
162-A \fBcron\fP(8) job typically runs this script at a quiet time every Sunday,
163-but you may need to run it manually once for a new MAAS installation.
164-
165-.SH FILES
166-\fI/etc/maas/import_pxe_files\fP, \fI/etc/cron.d/maas\-import\-pxe\-files\fP
167-
168-.SH "SEE ALSO"
169-.BR maas\-import\-ephemerals (8),
170-.BR cron (8),
171-.BR wget (1)
172-
173-.TP
174-\fIhttp://launchpad.net/maas\fP
175-.PD
176-
177-.SH AUTHOR
178-This manual page and the script were written by Jeroen Vermeulen
179-<jeroen.vermeulen@canonical.com> for Ubuntu systems, but may be used by
180-others. Permission is granted to copy, distribute and/or modify this
181-document and the utility under the terms of the GNU General Public
182-License, Version 3 published by the Free Software Foundation.
183-
184-The complete text of the GNU General Public License can be found in
185-\fI/usr/share/common-licenses/GPL\fP on Debian/Ubuntu systems, or on
186-the web at \fIhttp://www.gnu.org/licenses/gpl.txt\fP.