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

[Nick Veitch]

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

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.

[Gavin Panella (allenap)]

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

review: Approve

[Nick Veitch (evilnick)]

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

=== modified file 'docs/conf.py'
--- docs/conf.py	2012-11-08 12:55:51 +0000
+++ docs/conf.py	2012-11-19 11:55:27 +0000
@@ -230,6 +230,10 @@
 # (source start file, name, description, authors, manual section).
 man_pages = [
     ('man/maas-cli.8', 'maas-cli', u'MAAS API commandline utility',
+     [u'Canonical 2012'], 8),
+    ('man/maas-import-pxe-files.8', 'maas-import-pxe-files', u'MAAS helper script',
+     [u'Canonical 2012'], 8),
+    ('man/maas.8', 'maas', u'MAAS administration tool',
      [u'Canonical 2012'], 8)
 ]
 

=== modified file 'docs/man/maas-cli.8.rst'
--- docs/man/maas-cli.8.rst	2012-10-25 13:38:22 +0000
+++ docs/man/maas-cli.8.rst	2012-11-19 11:55:27 +0000
@@ -21,6 +21,8 @@
 ^^^^^^^^^^^^^^^^^^^^^
 For more documentation of MAAS, please see https://maas.ubuntu.com/docs
 
-
+See Also
+^^^^^^^^
+`maas`, `maas-import-pxe-files`
 
 

=== added file 'docs/man/maas-import-pxe-files.8.rst'
--- docs/man/maas-import-pxe-files.8.rst	1970-01-01 00:00:00 +0000
+++ docs/man/maas-import-pxe-files.8.rst	2012-11-19 11:55:27 +0000
@@ -0,0 +1,48 @@
+maas-import-pxe-files
+---------------------
+
+USAGE
+^^^^^
+
+maas-import-pxe-files [-h, --help]
+
+DESCRIPTION
+^^^^^^^^^^^
+
+This is a helper script for the MAAS software. It downloads Ubuntu 
+images and organises them for use by MAAS in commissioning nodes.
+The script is usually run regularly by a cron task, though it 
+needs to be run manually the first time a MAAS system is installed.
+Images that are already in place are kept unchanged, unless the
+version in the archive has since been updated.
+
+The script reads a configuration file /etc/maas/import_pxe_files in
+order to determine:
+
+**ARCHIVE:** Location of the Ubuntu download archive
+
+**RELEASES:** Ubuntu releases to download
+
+**ARCHES:** Architectures for which images should be downloaded
+
+To support development setups that run directly from a code branch, it will
+also look for /etc/maas/import_pxe_files relative to the current
+directory.
+
+The script uses `wget` to download the kernel and initrd image for
+each architecture in ARCHES and each release in RELEASES.  In addition it
+copies the Intel-architecture pre-boot loader `pxelinux.0` (plus some
+of its modules such as `chain.c32`) from its installed location in
+/usr/lib/syslinux/.
+
+These images are the minimum that's required to start installing a node.
+During installation, a node may download its packages over the network.
+
+
+Further Documentation
+^^^^^^^^^^^^^^^^^^^^^
+For more documentation of MAAS, please see https://maas.ubuntu.com/docs
+
+See Also
+^^^^^^^^
+`maas`, `maas-cli`

=== added file 'docs/man/maas.8.rst'
--- docs/man/maas.8.rst	1970-01-01 00:00:00 +0000
+++ docs/man/maas.8.rst	2012-11-19 11:55:27 +0000
@@ -0,0 +1,41 @@
+maas
+----
+
+USAGE
+^^^^^
+
+maas  [-h, --help] createsuperuser | changepassword | shell
+
+DESCRIPTION
+^^^^^^^^^^^
+
+The `maas` command is part of Canonical's Metal As A Service software. It is 
+derived from and can be used similarly to the `django-admin` command, and must 
+be run with root privileges. 
+
+For the end user, there are only three subcommands of interest.
+
+**createsuperuser**
+  This subcommand is used to create a superuser for the
+  MAAS install. The suggested username is "root". This command usually only 
+  needs to be run when installing MAAS for the first time.
+
+**changepassword**
+  This subcommand is used to change the superuser password
+  for the MAAS install. You will be prompted to enter a new password, and then
+  enter it once again to verify.
+
+**shell**
+  This subcommand may be useful for debugging installed systems. It 
+  will open a new python shell environment with the correct django environment
+  for working with the installed MAAS software.
+
+  
+Further Documentation
+^^^^^^^^^^^^^^^^^^^^^
+For more documentation of MAAS, please see https://maas.ubuntu.com/docs
+
+See Also
+^^^^^^^^
+`maas-cli`, `maas-import-pxe-files`
+

=== removed file 'man/maas-import-pxe-files.8'
--- man/maas-import-pxe-files.8	2012-08-30 13:09:12 +0000
+++ man/maas-import-pxe-files.8	1970-01-01 00:00:00 +0000
@@ -1,54 +0,0 @@
-.TH maas\-import\-pxe-files 8 "16 July 2012" maas "maas"
-.SH NAME
-\fBmaas\-import\-pxe-files\fP \- import Ubuntu install images into MAAS
-
-.SH DESCRIPTION
-\fBmaas\-import\-pxe\-files\fP downloads Ubuntu images and installs them into
-MAAS.  The MAAS server needs these images to provides nodes with operating
-systems.  Images that are already in place are kept unchanged, unless the
-version in the archive has since been updated.
-
-The script reads a configuration file \fI/etc/maas/import_pxe_files\fP in
-order to determine:
- - ARCHIVE: Location of the Ubuntu download archive
- - RELEASES: Ubuntu releases to download
- - ARCHES: Architectures for which images should be downloaded
-
-(To support development setups that run directly from a code branch, it will
-also look for \fIetc/maas/import_pxe_files\fP relative to the current
-directory).
-
-The script uses \fBwget\fP(1) to download the kernel and initrd image for
-each architecture in ARCHES and each release in RELEASES.  In addition it
-copies the Intel-architecture pre-boot loader \fBpxelinux.0\fP (plus some
-of its modules such as \fBchain.c32\fP) from its installed location in
-\fI/usr/lib/syslinux/\fP.
-
-These images are the minimum that's required to start installng a node.
-During installation, a node may download its packages over the network.
-
-A \fBcron\fP(8) job typically runs this script at a quiet time every Sunday,
-but you may need to run it manually once for a new MAAS installation.
-
-.SH FILES
-\fI/etc/maas/import_pxe_files\fP, \fI/etc/cron.d/maas\-import\-pxe\-files\fP
-
-.SH "SEE ALSO"
-.BR maas\-import\-ephemerals (8),
-.BR cron (8),
-.BR wget (1)
-
-.TP
-\fIhttp://launchpad.net/maas\fP
-.PD
-
-.SH AUTHOR
-This manual page and the script were written by Jeroen Vermeulen
-<[e-mail]> for Ubuntu systems, but may be used by
-others.  Permission is granted to copy, distribute and/or modify this
-document and the utility under the terms of the GNU General Public
-License, Version 3 published by the Free Software Foundation.
-
-The complete text of the GNU General Public License can be found in
-\fI/usr/share/common-licenses/GPL\fP on Debian/Ubuntu systems, or on
-the web at \fIhttp://www.gnu.org/licenses/gpl.txt\fP.