[PATCH 0/4] Add DITA help pages
This is the difference between this and the previous patchset (v1): - The *.dita files have more meaningful names. - The Makefile reads all *.dita/*.html files dynamically (no need to list each file). Crístian Viana (4): doc: Add DITA help pages doc: Add help files to dist packages doc: Export the help pages to cherrypy doc: Ignore the generated files .gitignore | 1 + configure.ac | 1 + contrib/DEBIAN/control.in | 2 +- contrib/kimchi.spec.fedora.in | 5 ++++ contrib/kimchi.spec.suse.in | 5 ++++ docs/README.md | 7 ++--- src/kimchi/server.py | 5 ++++ ui/pages/Makefile.am | 2 +- ui/pages/help/Makefile.am | 30 ++++++++++++++++++++++ ui/pages/help/dita-help.xsl | 24 ++++++++++++++++++ ui/pages/help/guests.dita | 47 ++++++++++++++++++++++++++++++++++ ui/pages/help/storage.dita | 45 +++++++++++++++++++++++++++++++++ ui/pages/help/templates.dita | 59 +++++++++++++++++++++++++++++++++++++++++++ 13 files changed, 228 insertions(+), 5 deletions(-) create mode 100644 ui/pages/help/Makefile.am create mode 100644 ui/pages/help/dita-help.xsl create mode 100644 ui/pages/help/guests.dita create mode 100644 ui/pages/help/storage.dita create mode 100644 ui/pages/help/templates.dita -- 1.8.5.3
Kimchi's help pages will be provided in a specific XML format, DITA - Darwin Information Typing Architecture, and they will be converted automatically to HTML files during build time. To build the HTML files, just type: $ make -C ui/pages/help The main "Makefile" will also execute that command above. Signed-off-by: Crístian Viana <vianac@linux.vnet.ibm.com> --- configure.ac | 1 + ui/pages/Makefile.am | 2 +- ui/pages/help/Makefile.am | 30 ++++++++++++++++++++++ ui/pages/help/dita-help.xsl | 24 ++++++++++++++++++ ui/pages/help/guests.dita | 47 +++++++++++++++++++++++++++++++++++ ui/pages/help/storage.dita | 45 +++++++++++++++++++++++++++++++++ ui/pages/help/templates.dita | 59 ++++++++++++++++++++++++++++++++++++++++++++ 7 files changed, 207 insertions(+), 1 deletion(-) create mode 100644 ui/pages/help/Makefile.am create mode 100644 ui/pages/help/dita-help.xsl create mode 100644 ui/pages/help/guests.dita create mode 100644 ui/pages/help/storage.dita create mode 100644 ui/pages/help/templates.dita diff --git a/configure.ac b/configure.ac index a30a934..c0bc538 100644 --- a/configure.ac +++ b/configure.ac @@ -76,6 +76,7 @@ AC_CONFIG_FILES([ ui/libs/themes/base/Makefile ui/libs/themes/base/images/Makefile ui/pages/Makefile + ui/pages/help/Makefile ui/pages/tabs/Makefile contrib/Makefile contrib/DEBIAN/Makefile diff --git a/ui/pages/Makefile.am b/ui/pages/Makefile.am index 5705abb..8d72398 100644 --- a/ui/pages/Makefile.am +++ b/ui/pages/Makefile.am @@ -18,7 +18,7 @@ # See the License for the specific language governing permissions and # limitations under the License. -SUBDIRS = tabs +SUBDIRS = help tabs htmldir = $(datadir)/kimchi/ui/pages diff --git a/ui/pages/help/Makefile.am b/ui/pages/help/Makefile.am new file mode 100644 index 0000000..61ea209 --- /dev/null +++ b/ui/pages/help/Makefile.am @@ -0,0 +1,30 @@ +# Copyright IBM Corp, 2014 +# +# Authors: +# Crístian Viana <vianac@linux.vnet.ibm.com> +# +# This library is free software; you can redistribute it and/or +# modify it under the terms of the GNU Lesser General Public +# License as published by the Free Software Foundation; either +# version 2.1 of the License, or (at your option) any later version. +# +# This library is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +# Lesser General Public License for more details. +# +# You should have received a copy of the GNU Lesser General Public +# License along with this library; if not, write to the Free Software +# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + +DITA_HTML_FILES = $(patsubst %.dita,%.html,$(wildcard *.dita)) $(wildcard *.html) +DITA_XSL_FILE = dita-help.xsl + +helpdir = $(datadir)/kimchi/ui/pages/help + +dist_help_DATA = $(DITA_HTML_FILES) $(NULL) + +%.html: %.dita $(DITA_XSL_FILE) + xsltproc -o $@ $(DITA_XSL_FILE) $< + +CLEANFILES = $(DITA_HTML_FILES) diff --git a/ui/pages/help/dita-help.xsl b/ui/pages/help/dita-help.xsl new file mode 100644 index 0000000..18f9496 --- /dev/null +++ b/ui/pages/help/dita-help.xsl @@ -0,0 +1,24 @@ +<?xml version="1.0" encoding="UTF-8"?> +<xsl:stylesheet version="1.0" + xmlns:xsl="http://www.w3.org/1999/XSL/Transform" + xmlns="http://www.w3.org/1999/xhtml"> + <xsl:output method="xml" indent="yes" encoding="UTF-8" /> + + <xsl:template match="/"> + <html> + <head> + <title><xsl:value-of select="/cshelp/title" /></title> + <link rel="shortcut icon" href="../images/logo.ico" /> + </head> + <body> + <xsl:apply-templates select="//cshelp" /> + </body> + </html> + </xsl:template> + + <xsl:template match="cshelp"> + <h1><xsl:value-of select="title" /></h1> + <p class="shortdesc"><xsl:value-of select="shortdesc" /></p> + <p class="csbody"><xsl:copy-of select="csbody/node()" /></p> + </xsl:template> +</xsl:stylesheet> diff --git a/ui/pages/help/guests.dita b/ui/pages/help/guests.dita new file mode 100644 index 0000000..cc6294c --- /dev/null +++ b/ui/pages/help/guests.dita @@ -0,0 +1,47 @@ +<?xml version="1.0" encoding="UTF-8"?> +<?Pub Sty _display FontColor="red"?> +<?Pub Inc?> +<cshelp id="kimhvirtm" xml:lang="en-us"> + <title>Virtual machines</title> + <shortdesc>The Virtual machines page lists the defined KVM virtual +machines.</shortdesc> + <csprolog> + <csmetadata> + <cswindowtitle>Title of window or panel associated with this help; +for review output only.</cswindowtitle> + <cswidgetlabel>Name of field or control associated with this help; +for review output only</cswidgetlabel> + </csmetadata> + </csprolog> + <csbody> + <p>For each virtual machine, the following information is displayed:<dl><dlentry><dt>Name</dt><dd>Name of the virtual machine.</dd></dlentry><dlentry><dt>CPU</dt><dd>Percentage of processor utilization in the virtual machine.</dd></dlentry><dlentry><dt>Network I/O</dt><dd>Network input/output transmission rate in KB per seconds.</dd></dlentry><dlentry><dt>Disk I/O</dt><dd> Disk input/output transmission rate in KB per seconds.</dd></dlentry><dlentry><dt>Console</dt><dd>Current state of guest operating system console.</dd></dlentry></dl></p> + <p>The following actions icons are displayed for each virtual machine:<dl><dlentry><dt>Reload</dt><dd>Click to reload the displayed data. </dd></dlentry><dlentry><dt>Power</dt><dd>Click to power on the virtual machine. If the icon is red, the +power is off; if the icon is green, the power is on.</dd></dlentry></dl> </p> + <p>The following actions can be selected for each virtual machine:<ul><li>Select <uicontrol>VNC</uicontrol> to connect to the remote console +for the virtual machine.</li><li>Select <uicontrol>Delete</uicontrol> to delete the virtual machine.</li></ul>To create a virtual machine, click the <uicontrol>plus (+)</uicontrol> icon +in the upper right of the page.</p> + </csbody> + <cshelp id="kimhvirtmcrt" xml:lang="en-us"> + <title>Create virtual machine</title> + <shortdesc>Create a virtual machine using an existing template.</shortdesc> + <csprolog> + <csmetadata> + <cswindowtitle>Title of window or panel associated with this help; +for review output only.</cswindowtitle> + <cswidgetlabel>Name of field or control associated with this help; +for review output only</cswidgetlabel> + </csmetadata> + </csprolog> + <csbody> + <p> + <ol> + <li>Type the name to be used to identify the virtual machine.</li> + <li>Click to select a template.</li> + <li>Click <uicontrol>Create</uicontrol>.</li> + </ol> + </p> + </csbody> + </cshelp> + <?Pub Caret -1?> +</cshelp> +<?Pub *0000002746?> diff --git a/ui/pages/help/storage.dita b/ui/pages/help/storage.dita new file mode 100644 index 0000000..f9ae93e --- /dev/null +++ b/ui/pages/help/storage.dita @@ -0,0 +1,45 @@ +<?xml version="1.0" encoding="UTF-8"?> +<?xml-stylesheet href="dita.xsl" type="text/xsl" ?> +<?Pub Sty _display FontColor="red"?> +<?Pub Inc?> +<cshelp id="kimhstor" xml:lang="en-us"> + <title>Storage</title> + <shortdesc>The Storage page lists the available storage pools, including the default storage pool.</shortdesc> + <csprolog> + <csmetadata> + <cswindowtitle>Title of window or panel associated with this help; for review output only.</cswindowtitle> + <cswidgetlabel>Name of field or control associated with this help; for review output only</cswidgetlabel> + </csmetadata> + </csprolog> + <csbody> + <p>For each storage pool, the following information is displayed:<dl><dlentry><dt>Name</dt><dd>Name of the storage pool and percentage used.</dd></dlentry><dlentry><dt>State</dt><dd>State of the storage pool, active (green) or inactive (red). </dd></dlentry><dlentry><dt>Location</dt><dd>File path to the location of the storage pool.</dd></dlentry><dlentry><dt>Type</dt><dd><uicontrol>dir</uicontrol> for directory.</dd></dlentry><dlentry><dt>Capacity</dt><dd>Amount of space in the storage pool.</dd></dlentry><dlentry><dt>Allocated</dt><dd>Amount of space already allocated in the storage pool.</dd></dlentry></dl></p> + <p>The following actions can be selected for each storage pool:<ul><li>Select <uicontrol>Activate</uicontrol> to activate the storage +pool so that it can be used.</li><li>Select <uicontrol>Undefine</uicontrol> to remove an inactive storage +pool.</li></ul></p> + <p>To display storage volume details for a storage pool, click the +arrow on the right side of the storage pool row. Details include +the following:<dl><dlentry><dt>Type</dt><dd>The type of storage pool, for example, dir or disk.</dd></dlentry><dlentry><dt>Format</dt><dd>The format, varying dependent on the type.</dd></dlentry><dlentry><dt>Capacity</dt><dd>Size of the storage volume.</dd></dlentry><dlentry><dt>Allocated</dt><dd>Amount of space already allocated in the storage pool.</dd></dlentry></dl>To define a storage pool, click the <uicontrol>plus +(+)</uicontrol> icon in the upper right of the display.</p> + </csbody> + <cshelp id="kimhdefstor" xml:lang="en-us"> + <title>Define a storage pool</title> + <shortdesc> Define a storage pool.</shortdesc> + <csprolog> + <csmetadata> + <cswindowtitle>Title of window or panel associated with this help; for review output only.</cswindowtitle> + <cswidgetlabel>Name of field or control associated with this help; for review output only</cswidgetlabel> + </csmetadata> + </csprolog> + <csbody> + <p> + <ol> + <li>Type the name to be used to identify the storage pool.</li> + <li>Type the file path to the storage pool.</li> + <li>Click <uicontrol>Create</uicontrol>.</li> + </ol> + </p> + </csbody> + </cshelp> + <?Pub Caret -1?> +</cshelp> +<?Pub *0000003013?> diff --git a/ui/pages/help/templates.dita b/ui/pages/help/templates.dita new file mode 100644 index 0000000..0a9bcff --- /dev/null +++ b/ui/pages/help/templates.dita @@ -0,0 +1,59 @@ +<?xml version="1.0" encoding="UTF-8"?> +<?Pub Sty _display FontColor="red"?> +<?Pub Inc?> +<cshelp id="kimhtempl" xml:lang="en-us"> + <title>Templates</title> + <shortdesc>The Templates page shows the defined virtual machine templates +that can be used to create KVM virtual machines.</shortdesc> + <csprolog> + <csmetadata> + <cswindowtitle>Title of window or panel associated with this help; +for review output only.</cswindowtitle> + <cswidgetlabel>Name of field or control associated with this help; +for review output only</cswidgetlabel> + </csmetadata> + </csprolog> + <csbody> + <p>For each template, the following information is displayed:<dl><dlentry><dt>OS</dt><dd>Name of the operating system or distribution.</dd></dlentry><dlentry><dt>Version</dt><dd>Version of the operating system or distribution.</dd></dlentry><dlentry><dt>CPU</dt><dd>Number of processors defined for the template.</dd></dlentry><dlentry><dt>Memory</dt><dd>Amount of random access memory to be allocated, in MB.</dd></dlentry></dl></p> + <p>The following actions can be selected for each template:<ul><li>Select <uicontrol>Edit</uicontrol> to edit the template.</li><li>Select <uicontrol>Delete</uicontrol> to delete the template.</li></ul>To add a template, click the <uicontrol>plus (+)</uicontrol> icon +in the upper right of the display.</p> + </csbody> + <cshelp id="kimhedittempl" xml:lang="en-us"> + <title>Edit template</title> + <shortdesc>Edit an existing template.</shortdesc> + <csprolog> + <csmetadata> + <cswindowtitle>Title of window or panel associated with this help; +for review output only.</cswindowtitle> + <cswidgetlabel>Name of field or control associated with this help; +for review output only</cswidgetlabel> + </csmetadata> + </csprolog> + <csbody> + <p><ol><li>Edit the following information for the template:<dl><dlentry><dt>Name</dt><dd>Name of the template.</dd></dlentry><dlentry><dt>CPU</dt><dd>Number of processors defined for the template.</dd></dlentry><dlentry><dt>Memory</dt><dd>Memory to be allocated to the virtual machine.</dd></dlentry></dl></li><li>Click <uicontrol>Save</uicontrol>.</li></ol>The following information is displayed but cannot be edited:<dl><dlentry><dt>Vendor</dt><dd>The name of the company that created the operating system or distribution +that the template is configured to use.</dd></dlentry><dlentry><dt>Version</dt><dd>The version of the operating system or distribution that the template +is configured to use.</dd></dlentry></dl></p> + </csbody> + </cshelp> + <?Pub Caret -1?> + <cshelp id="kimhaddtempl"> + <title>Add template</title> + <shortdesc>Add a template from source media.</shortdesc> + <csbody> + <p>Select the location from the following options:<ol><li>Select the location of the source media from the following options:<dl><dlentry><dt>Local ISO image</dt><dd>Select to scan storage pools for installation ISO images available +on the system.</dd></dlentry><dlentry><dt>Remote ISO image</dt><dd>Select to specify a remote location for an installation ISO image.</dd></dlentry></dl></li><li>Click <uicontrol>Create</uicontrol>.</li></ol></p> + </csbody> + </cshelp> + <cshelp id="kimhaddloct"> + <title>Add template - local ISO image</title> + <shortdesc>Add a template from a local ISO image.</shortdesc> + <csbody> + <p>The ISO images available on the system are displayed.<dl><dlentry><dt>OS</dt><dd>Name of the operating system or distribution.</dd></dlentry><dlentry><dt>Version</dt><dd>Version of the operating system or distribution.</dd></dlentry><dlentry><dt>Size</dt><dd>Size of the ISO image.</dd></dlentry></dl></p> + <p>To create a template from an ISO image, complete the following +steps:<ol><li>Choose from the following options:<ul><li>Select an ISO image from which to create a template.</li><li>Select the <uicontrol>All</uicontrol> check box to create a template +from each listed ISO image.</li><li>Select the <uicontrol>I want to use a specific file</uicontrol> check +box to specify a path to the ISO image.</li></ul></li><li>Click <uicontrol>Create</uicontrol>.</li></ol></p> + </csbody> + </cshelp> +</cshelp> +<?Pub *0000004376?> -- 1.8.5.3
The DITA help files should also be included in the RPM and DEB files which will distribute Kimchi. Only the generated HTML files will be added Also, update the README to list the dependecies needed to convert the DITA files to HTML. Signed-off-by: Crístian Viana <vianac@linux.vnet.ibm.com> --- contrib/DEBIAN/control.in | 2 +- contrib/kimchi.spec.fedora.in | 5 +++++ contrib/kimchi.spec.suse.in | 5 +++++ docs/README.md | 7 ++++--- 4 files changed, 15 insertions(+), 4 deletions(-) diff --git a/contrib/DEBIAN/control.in b/contrib/DEBIAN/control.in index 762b3a0..0952490 100644 --- a/contrib/DEBIAN/control.in +++ b/contrib/DEBIAN/control.in @@ -22,6 +22,6 @@ Depends: python-cherrypy3 (>= 3.2.0), python-lxml, open-iscsi, firewalld -Build-Depends: +Build-Depends: libxslt Maintainer: Aline Manera <alinefm@br.ibm.com> Description: Kimchi web server diff --git a/contrib/kimchi.spec.fedora.in b/contrib/kimchi.spec.fedora.in index 5140c5e..0511527 100644 --- a/contrib/kimchi.spec.fedora.in +++ b/contrib/kimchi.spec.fedora.in @@ -28,6 +28,7 @@ Requires: python-ipaddr Requires: python-lxml Requires: nfs-utils Requires: iscsi-initiator-utils +BuildRequires: libxslt %if 0%{?rhel} == 6 Requires: python-ordereddict @@ -175,6 +176,7 @@ rm -rf $RPM_BUILD_ROOT %{_datadir}/kimchi/ui/libs/themes/base/images/*.gif %{_datadir}/kimchi/ui/libs/themes/base/jquery-ui.min.css %{_datadir}/kimchi/ui/pages/*.html.tmpl +%{_datadir}/kimchi/ui/pages/help/*.html %{_datadir}/kimchi/ui/pages/tabs/*.html.tmpl %{_sysconfdir}/kimchi/kimchi.conf %{_sysconfdir}/kimchi/distros.d/debian.json @@ -195,6 +197,9 @@ rm -rf $RPM_BUILD_ROOT %endif %changelog +* Tue Feb 11 2014 Crístian Viana <vianac@linux.vnet.ibm.com> 1.1.0 +- Add help pages and XSLT dependency + * Tue Jul 16 2013 Adam Litke <agl@us.ibm.com> 0.1.0-1 - Adapted for autotools build diff --git a/contrib/kimchi.spec.suse.in b/contrib/kimchi.spec.suse.in index 15db59b..cbb7b67 100644 --- a/contrib/kimchi.spec.suse.in +++ b/contrib/kimchi.spec.suse.in @@ -23,6 +23,7 @@ Requires: python-ipaddr Requires: python-lxml Requires: nfs-client Requires: open-iscsi +BuildRequires: libxslt-tools %if 0%{?sles_version} == 11 Requires: python-ordereddict @@ -95,6 +96,7 @@ rm -rf $RPM_BUILD_ROOT %{_datadir}/kimchi/ui/libs/themes/base/images/*.gif %{_datadir}/kimchi/ui/libs/themes/base/jquery-ui.min.css %{_datadir}/kimchi/ui/pages/*.html.tmpl +%{_datadir}/kimchi/ui/pages/help/*.html %{_datadir}/kimchi/ui/pages/tabs/*.html.tmpl %{_sysconfdir}/kimchi/kimchi.conf %{_sysconfdir}/kimchi/distros.d/debian.json @@ -105,6 +107,9 @@ rm -rf $RPM_BUILD_ROOT %{_initrddir}/kimchid %changelog +* Tue Feb 11 2014 Crístian Viana <vianac@linux.vnet.ibm.com> 1.1.0 +- Add help pages and XSLT dependency + * Thu Jul 18 2013 Adam Litke <agl@us.ibm.com> 0.1.0-1 - Adapted for autotools build - Split Suse and Fedora spec files diff --git a/docs/README.md b/docs/README.md index 0b22b9d..fcf53c5 100644 --- a/docs/README.md +++ b/docs/README.md @@ -53,7 +53,7 @@ Install Dependencies PyPAM m2crypto python-jsonschema rpm-build \ qemu-kvm python-psutil python-ethtool sos \ python-ipaddr python-lxml nfs-utils \ - iscsi-initiator-utils + iscsi-initiator-utils libxslt # If using RHEL6, install the following additional packages: $ sudo yum install python-unittest2 python-ordereddict # Restart libvirt to allow configuration changes to take effect @@ -75,7 +75,7 @@ for more information on how to configure your system to access this repository. python-pam python-m2crypto python-jsonschema \ qemu-kvm libtool python-psutil python-ethtool \ sosreport python-ipaddr python-lxml nfs-common \ - open-iscsi lvm2 + open-iscsi lvm2 xsltproc Packages version requirement: python-jsonschema >= 1.3.0 @@ -88,7 +88,8 @@ for more information on how to configure your system to access this repository. libvirt python-libxml2 python-imaging \ python-pam python-M2Crypto python-jsonschema \ rpm-build kvm python-psutil python-ethtool \ - python-ipaddr python-lxml nfs-client open-iscsi + python-ipaddr python-lxml nfs-client open-iscsi \ + libxslt-tools Packages version requirement: python-psutil >= 0.6.0 -- 1.8.5.3
The new DITA help pages will be exported to cherrypy under the URL "help/". For example, the help page "kimhstor.html" can be acessed in a local Kimchi installation at "http://localhost:8000/help/kimhstor.html". Signed-off-by: Crístian Viana <vianac@linux.vnet.ibm.com> --- src/kimchi/server.py | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/src/kimchi/server.py b/src/kimchi/server.py index d3ca617..6dd0404 100644 --- a/src/kimchi/server.py +++ b/src/kimchi/server.py @@ -122,6 +122,11 @@ class Server(object): '/favicon.ico': { 'tools.staticfile.on': True, 'tools.staticfile.filename': '%s/images/logo.ico' % paths.ui_dir + }, + '/help': { + 'tools.staticdir.on': True, + 'tools.staticdir.dir': 'ui/pages/help', + 'tools.nocache.on': False } } -- 1.8.5.3
As the HTML files are generated according to the DITA files, we do not need to include them to the Git repository. They can always be regenerated when needed. Signed-off-by: Crístian Viana <vianac@linux.vnet.ibm.com> --- .gitignore | 1 + 1 file changed, 1 insertion(+) diff --git a/.gitignore b/.gitignore index a3b7f6f..67878e2 100644 --- a/.gitignore +++ b/.gitignore @@ -35,3 +35,4 @@ po/gen-pot *.orig *.rej *.pem +ui/pages/help/*.html -- 1.8.5.3
participants (2)
-
Aline Manera -
Crístian Viana