openstack/heat
Code Issues Proposed changes

A new documention structure, ready for contributions

Browse Source 
Here are some skeletons for the documentation which will need to be written.

doc/source
	A Sphinx based document which will be aimed at heat developers.
    	This also contains .rst files which generate the man files
doc/docbkx/api-ref
	Docbook and WADL for the REST API, with the intent of moving this
	to api-site to publish to api.openstack.org
doc/docbkx/heat-admin
	Docbook manual targeted at Heat admins, with the intent of moving this
        to openstack-manuals to publish to docs.openstack.org
doc/docbkx/heat-cli
	Docbook manual targeted at users of the Heat CLI, with the intent of
	moving this to openstack-manuals to publish to docs.openstack.org

Dude, wheres my man pages?
docs/man
	is deleted, now generated into doc/build/man

Packaging will need to be updated to generate the man pages

Change-Id: Idf2f37086b6f97df18ed57172de2f9e3d4c7706a
This commit is contained in:
Steve Baker 2012-12-14 14:13:05 +13:00
parent 083c0cc2b0
commit c4777794e7
33 changed files with 1729 additions and 604 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
doc/.gitignore vendored Normal file
View File

@ -0,0 +1,2 @@
target/
build/

153
doc/Makefile Normal file
View File

@ -0,0 +1,153 @@
# Makefile for Sphinx documentation
#
# You can set these variables from the command line.
SPHINXOPTS =
SPHINXBUILD = sphinx-build
PAPER =
BUILDDIR = build
# Internal variables.
PAPEROPT_a4 = -D latex_paper_size=a4
PAPEROPT_letter = -D latex_paper_size=letter
ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
# the i18n builder cannot share the environment and doctrees with the others
I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext
help:
@echo "Please use \`make <target>' where <target> is one of"
@echo " html to make standalone HTML files"
@echo " dirhtml to make HTML files named index.html in directories"
@echo " singlehtml to make a single large HTML file"
@echo " pickle to make pickle files"
@echo " json to make JSON files"
@echo " htmlhelp to make HTML files and a HTML help project"
@echo " qthelp to make HTML files and a qthelp project"
@echo " devhelp to make HTML files and a Devhelp project"
@echo " epub to make an epub"
@echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
@echo " latexpdf to make LaTeX files and run them through pdflatex"
@echo " text to make text files"
@echo " man to make manual pages"
@echo " texinfo to make Texinfo files"
@echo " info to make Texinfo files and run them through makeinfo"
@echo " gettext to make PO message catalogs"
@echo " changes to make an overview of all changed/added/deprecated items"
@echo " linkcheck to check all external links for integrity"
@echo " doctest to run all doctests embedded in the documentation (if enabled)"
clean:
-rm -rf $(BUILDDIR)/*
html:
$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
@echo
@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
dirhtml:
$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
@echo
@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
singlehtml:
$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
@echo
@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
pickle:
$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
@echo
@echo "Build finished; now you can process the pickle files."
json:
$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
@echo
@echo "Build finished; now you can process the JSON files."
htmlhelp:
$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
@echo
@echo "Build finished; now you can run HTML Help Workshop with the" \
".hhp project file in $(BUILDDIR)/htmlhelp."
qthelp:
$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
@echo
@echo "Build finished; now you can run "qcollectiongenerator" with the" \
".qhcp project file in $(BUILDDIR)/qthelp, like this:"
@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/Heat.qhcp"
@echo "To view the help file:"
@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/Heat.qhc"
devhelp:
$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
@echo
@echo "Build finished."
@echo "To view the help file:"
@echo "# mkdir -p $$HOME/.local/share/devhelp/Heat"
@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/Heat"
@echo "# devhelp"
epub:
$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
@echo
@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
latex:
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
@echo
@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
@echo "Run \`make' in that directory to run these through (pdf)latex" \
"(use \`make latexpdf' here to do that automatically)."
latexpdf:
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
@echo "Running LaTeX files through pdflatex..."
$(MAKE) -C $(BUILDDIR)/latex all-pdf
@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
text:
$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
@echo
@echo "Build finished. The text files are in $(BUILDDIR)/text."
man:
$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
@echo
@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
texinfo:
$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
@echo
@echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
@echo "Run \`make' in that directory to run these through makeinfo" \
"(use \`make info' here to do that automatically)."
info:
$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
@echo "Running Texinfo files through makeinfo..."
make -C $(BUILDDIR)/texinfo info
@echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."
gettext:
$(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
@echo
@echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."
changes:
$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
@echo
@echo "The overview file is in $(BUILDDIR)/changes."
linkcheck:
$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
@echo
@echo "Link check complete; look for any errors in the above output " \
"or in $(BUILDDIR)/linkcheck/output.txt."
doctest:
$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
@echo "Testing of doctests in the sources finished, look at the " \
"results in $(BUILDDIR)/doctest/output.txt."

35
doc/README.rst Normal file
View File

@ -0,0 +1,35 @@
===========================
Building the developer docs
===========================
For user and admin docs, go to the directory `doc/docbkx`.
Dependencies
============
Sphinx_
You'll need sphinx (the python one) and if you are
using the virtualenv you'll need to install it in the virtualenv
specifically so that it can load the cinder modules.
::
sudo yum install python-sphinx
sudo pip-python install sphinxcontrib-httpdomain
Use `make`
==========
Just type make::
make
Look in the Makefile for more targets.
To build the man pages:
make man
To build the developer documentation as HTML:
make html

35
doc/docbkx/README.rst Normal file
View File

@ -0,0 +1,35 @@
================================
Building the user and admin docs
================================
This documentation should eventually end up in the OpenStack documentation
repositories `api-site` and `openstack-manuals`.
Dependencies
============
on Ubuntu:
sudo apt-get install maven
on Fedora Core:
sudo yum install maven
Use `mvn`
=========
Build the REST API reference manual:
cd api-ref
mvn clean generate-sources
Build the Heat admin guide:
cd heat-admin
mvn clean generate-sources
Build the Heat CLI guide:
cd heat-cli-guide
mvn clean generate-sources

76
doc/docbkx/api-ref/pom.xml Normal file
View File

@ -0,0 +1,76 @@
<project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
<!-- POM Build file for the Keystone Developer Guide -->
<modelVersion>4.0.0</modelVersion>
<groupId>org.openstack.identity</groupId>
<artifactId>docs</artifactId>
<version>1.0</version>
<packaging>jar</packaging>
<name>OpenStack API Page Project</name>
<profiles>
<profile>
<id>Rackspace Research Repositories</id>
<activation>
<activeByDefault>true</activeByDefault>
</activation>
<repositories>
<repository>
<id>rackspace-research</id>
<name>Rackspace Research Repository</name>
<url>http://maven.research.rackspacecloud.com/content/groups/public/</url>
</repository>
</repositories>
<pluginRepositories>
<pluginRepository>
<id>rackspace-research</id>
<name>Rackspace Research Repository</name>
<url>http://maven.research.rackspacecloud.com/content/groups/public/</url>
<snapshots>
<updatePolicy>always</updatePolicy>
</snapshots>
</pluginRepository>
</pluginRepositories>
</profile>
</profiles>
<properties>
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
<doctools.version>1.5.1</doctools.version>
</properties>
<build>
<plugins>
<plugin>
<groupId>com.rackspace.cloud.api</groupId>
<artifactId>clouddocs-maven-plugin</artifactId>
<version>${doctools.version}</version>
<executions>
<execution>
<id>g1</id>
<goals>
<goal>generate-html</goal>
</goals>
<phase>generate-sources</phase>
<configuration>
<highlightSource>false</highlightSource>
<enableGoogleAnalytics>1</enableGoogleAnalytics>
<googleAnalyticsId>UA-17511903-1</googleAnalyticsId>
</configuration>
</execution>
</executions>
<configuration>
<!-- These parameters apply to pdf and webhelp -->
<xincludeSupported>true</xincludeSupported>
<sourceDirectory>src/docbkx</sourceDirectory>
<includes>
api-ref.xml
</includes>
<profileSecurity>reviewer</profileSecurity>
<branding>openstack</branding>
<trimWadlUriCount>1</trimWadlUriCount>
<showXslMessages>true</showXslMessages>
</configuration>
</plugin>
</plugins>
</build>
</project>

24
doc/docbkx/api-ref/src/docbkx/api-ref.xml Normal file
View File

@ -0,0 +1,24 @@
<?xml version="1.0" encoding="UTF-8"?>
<book xmlns="http://docbook.org/ns/docbook"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:wadl="http://wadl.dev.java.net/2009/02"
version="5.0-extension RackBook-2.0" xml:id="api.openstack.org">
<info>
<title>Heat API</title>
<copyright>
<year>2012</year>
</copyright>
<legalnotice role="apache2">
<para/>
</legalnotice>
</info>
<chapter xml:id="object">
<title>Heat</title>
<para></para>
<wadl:resources
href="../wadls/heat-api/src/heat-api-1.0.wadl"
xmlns:wadl="http://wadl.dev.java.net/2009/02"/>
</chapter>
</book>

13
doc/docbkx/api-ref/src/wadls/heat-api/src/heat-api-1.0.wadl Normal file
View File

@ -0,0 +1,13 @@
<?xml version="1.0" encoding="UTF-8"?>
<!-- (C) 2012 OpenStack LLC., All Rights Reserved -->
<application xmlns="http://wadl.dev.java.net/2009/02"
xmlns:xsdxt="http://docs.rackspacecloud.com/xsd-ext/v1.0"
xmlns:wadl="http://wadl.dev.java.net/2009/02">
<resources base="https://heat.example.com/">
</resources>
</application>

16
doc/docbkx/heat-admin/app_core.xml Normal file
View File

@ -0,0 +1,16 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE appendix [
<!-- Some useful entities borrowed from HTML -->
<!ENTITY ndash "&#x2013;">
<!ENTITY mdash "&#x2014;">
<!ENTITY hellip "&#x2026;">
<!ENTITY plusmn "&#xB1;">
]>
<appendix xmlns="http://docbook.org/ns/docbook"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
xml:id="app_core">
<title>Core Configuration File Options</title>
<para>TODO</para>
</appendix>

69
doc/docbkx/heat-admin/bk-heat-admin-guide.xml Normal file
View File

@ -0,0 +1,69 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book[
<!-- Some useful entities borrowed from HTML -->
<!ENTITY ndash "&#x2013;">
<!ENTITY mdash "&#x2014;">
<!ENTITY hellip "&#x2026;">
<!ENTITY plusmn "&#xB1;">
]>
<book xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:svg="http://www.w3.org/2000/svg"
xmlns:m="http://www.w3.org/1998/Math/MathML"
xmlns:html="http://www.w3.org/1999/xhtml"
xmlns:db="http://docbook.org/ns/docbook"
version="5.0"
status="final"
xml:id="Heat-admin-guide-trunk">
<?rax pdf.url="../bk-heat-admin-guide-trunk.pdf"?>
<title>Heat Administration Guide</title>
<info>
<author>
<personname>
<firstname/>
<surname/>
</personname>
</author>
<copyright>
<year>2012</year>
<holder>OpenStack</holder>
</copyright>
<releaseinfo>Grizzly (2013.1)</releaseinfo>
<productname>Heat</productname>
<pubdate>2012-12-14</pubdate>
<legalnotice role="apache2">
<annotation>
<remark>Copyright details are filled in by the template.</remark>
</annotation>
</legalnotice>
<abstract>
<para>This document is intended for administrators interested in running the Heat Service. </para>
</abstract>
<revhistory>
<!-- ... continue adding more revisions here as you change this document using the markup shown below... -->
<revision>
<date>2012-12-14</date>
<revdescription>
<itemizedlist spacing="compact">
<listitem>
<para>First edition of this document.</para>
</listitem>
</itemizedlist>
</revdescription>
</revision>
</revhistory>
</info>
<xi:include href="ch_preface.xml"/>
<xi:include href="ch_overview.xml"/>
<xi:include href="ch_install.xml"/>
<xi:include href="ch_using.xml"/>
<xi:include href="ch_limitations.xml"/>
<xi:include href="app_core.xml"/>
</book>

19
doc/docbkx/heat-admin/ch_install.xml Normal file
View File

@ -0,0 +1,19 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter[
<!-- Some useful entities borrowed from HTML -->
<!ENTITY ndash "&#x2013;">
<!ENTITY mdash "&#x2014;">
<!ENTITY hellip "&#x2026;">
<!ENTITY plusmn "&#xB1;">
]>
<chapter
xmlns="http://docbook.org/ns/docbook"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink"
version="5.0"
xml:id="ch_install">
<title>Heat Installation</title>
<para> This chapter describes how to install the Heat Service
and get it up and running. </para>
</chapter>

43
doc/docbkx/heat-admin/ch_limitations.xml Normal file
View File

@ -0,0 +1,43 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter [
<!-- Some useful entities borrowed from HTML -->
<!ENTITY ndash "&#x2013;">
<!ENTITY mdash "&#x2014;">
<!ENTITY hellip "&#x2026;">
<!ENTITY plusmn "&#xB1;">
<!-- Useful for describing APIs -->
<!ENTITY GET '<command xmlns="http://docbook.org/ns/docbook">GET</command>'>
<!ENTITY PUT '<command xmlns="http://docbook.org/ns/docbook">PUT</command>'>
<!ENTITY POST '<command xmlns="http://docbook.org/ns/docbook">POST</command>'>
<!ENTITY DELETE '<command xmlns="http://docbook.org/ns/docbook">DELETE</command>'>
<!ENTITY CHECK '<inlinemediaobject xmlns="http://docbook.org/ns/docbook">
<imageobject role="fo">
<imagedata fileref="figures/Check_mark_23x20_02.svg"
format="SVG" scale="60"/>
</imageobject>
<imageobject role="html">
<imagedata fileref="../figures/Check_mark_23x20_02.png"
format="PNG" />
</imageobject>
</inlinemediaobject>'>
<!ENTITY ARROW '<inlinemediaobject xmlns="http://docbook.org/ns/docbook">
<imageobject role="fo">
<imagedata fileref="figures/Arrow_east.svg"
format="SVG" scale="60"/>
</imageobject>
<imageobject role="html">
<imagedata fileref="../figures/Arrow_east.png"
format="PNG" />
</imageobject>
</inlinemediaobject>'>
]>
<chapter xmlns="http://docbook.org/ns/docbook"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
xml:id="ch_limitations">
<title>Limitations</title>
<para>TODO</para>
</chapter>

57
doc/docbkx/heat-admin/ch_overview.xml Normal file
View File

@ -0,0 +1,57 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter [
<!-- Some useful entities borrowed from HTML -->
<!ENTITY ndash "&#x2013;">
<!ENTITY mdash "&#x2014;">
<!ENTITY hellip "&#x2026;">
<!ENTITY plusmn "&#xB1;">
<!-- Useful for describing APIs -->
<!ENTITY GET '<command xmlns="http://docbook.org/ns/docbook">GET</command>'>
<!ENTITY PUT '<command xmlns="http://docbook.org/ns/docbook">PUT</command>'>
<!ENTITY POST '<command xmlns="http://docbook.org/ns/docbook">POST</command>'>
<!ENTITY DELETE '<command xmlns="http://docbook.org/ns/docbook">DELETE</command>'>
<!ENTITY CHECK '<inlinemediaobject xmlns="http://docbook.org/ns/docbook">
<imageobject role="fo">
<imagedata fileref="figures/Check_mark_23x20_02.svg"
format="SVG" scale="60"/>
</imageobject>
<imageobject role="html">
<imagedata fileref="../figures/Check_mark_23x20_02.png"
format="PNG" />
</imageobject>
</inlinemediaobject>'>
<!ENTITY ARROW '<inlinemediaobject xmlns="http://docbook.org/ns/docbook">
<imageobject role="fo">
<imagedata fileref="figures/Arrow_east.svg"
format="SVG" scale="60"/>
</imageobject>
<imageobject role="html">
<imagedata fileref="../figures/Arrow_east.png"
format="PNG" />
</imageobject>
</inlinemediaobject>'>
<!ENTITY SENova 'services extension'>
<!ENTITY uSENova 'Services extension'>
<!ENTITY uuSENova 'Services Extension'>
<!ENTITY RSNova 'reset state extension'>
<!ENTITY uRSNova 'Reset state extension'>
<!ENTITY uuRSNova 'Reset State Extension'>
<!ENTITY ngCS 'next generation Rackspace Cloud Servers™ <link
xlink:href="http://www.rackspace.com/cloud/openstack/"
>powered by OpenStack</link>'>
<!ENTITY ungCS 'Next generation Rackspace Cloud Servers™ <link
xlink:href="http://www.rackspace.com/cloud/openstack/"
>powered by OpenStack</link>'>
]>
<chapter xmlns="http://docbook.org/ns/docbook"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
xml:id="ch_overview">
<title>Overview</title>
<para> This chapter describes the high-level concepts and
components of a Heat deployment. </para>
</chapter>

68
doc/docbkx/heat-admin/ch_preface.xml Normal file
View File

@ -0,0 +1,68 @@
<!DOCTYPE preface [
<!-- Some useful entities borrowed from HTML -->
<!ENTITY ndash "&#x2013;">
<!ENTITY mdash "&#x2014;">
<!ENTITY hellip "&#x2026;">
<!ENTITY plusmn "&#xB1;">
<!-- Useful for describing APIs -->
<!ENTITY GET '<command xmlns="http://docbook.org/ns/docbook">GET</command>'>
<!ENTITY PUT '<command xmlns="http://docbook.org/ns/docbook">PUT</command>'>
<!ENTITY POST '<command xmlns="http://docbook.org/ns/docbook">POST</command>'>
<!ENTITY DELETE '<command xmlns="http://docbook.org/ns/docbook">DELETE</command>'>
<!ENTITY CHECK '<inlinemediaobject xmlns="http://docbook.org/ns/docbook">
<imageobject role="fo">
<imagedata fileref="figures/Check_mark_23x20_02.svg"
format="SVG" scale="60"/>
</imageobject>
<imageobject role="html">
<imagedata fileref="../figures/Check_mark_23x20_02.png"
format="PNG" />
</imageobject>
</inlinemediaobject>'>
<!ENTITY ARROW '<inlinemediaobject xmlns="http://docbook.org/ns/docbook">
<imageobject role="fo">
<imagedata fileref="figures/Arrow_east.svg"
format="SVG" scale="60"/>
</imageobject>
<imageobject role="html">
<imagedata fileref="../figures/Arrow_east.png"
format="PNG" />
</imageobject>
</inlinemediaobject>'>
<!ENTITY SENova 'services extension'>
<!ENTITY uSENova 'Services extension'>
<!ENTITY uuSENova 'Services Extension'>
<!ENTITY RSNova 'reset state extension'>
<!ENTITY uRSNova 'Reset state extension'>
<!ENTITY uuRSNova 'Reset State Extension'>
<!ENTITY ngCS 'next generation Rackspace Cloud Servers™ <link
xlink:href="http://www.rackspace.com/cloud/openstack/"
>powered by OpenStack</link>'>
<!ENTITY ungCS 'Next generation Rackspace Cloud Servers™ <link
xlink:href="http://www.rackspace.com/cloud/openstack/"
>powered by OpenStack</link>'>
]>
<preface xmlns="http://docbook.org/ns/docbook"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
xml:id="ch_preface">
<title>Preface</title>
<section xml:id="Intended_Audience-d1e85">
<title>Intended Audience</title>
<para>TODO</para>
</section>
<section xml:id="Document_Change_History-d1e118">
<title>Document Change History</title>
<para>The most recent changes are described in the table
below:</para>
<?rax revhistory?>
</section>
<section xml:id="resources">
<title>Resources</title>
<para>TODO</para>
</section>
<?hard-pagebreak?>
</preface>

43
doc/docbkx/heat-admin/ch_using.xml Normal file
View File

@ -0,0 +1,43 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter [
<!-- Some useful entities borrowed from HTML -->
<!ENTITY ndash "&#x2013;">
<!ENTITY mdash "&#x2014;">
<!ENTITY hellip "&#x2026;">
<!ENTITY plusmn "&#xB1;">
<!-- Useful for describing APIs -->
<!ENTITY GET '<command xmlns="http://docbook.org/ns/docbook">GET</command>'>
<!ENTITY PUT '<command xmlns="http://docbook.org/ns/docbook">PUT</command>'>
<!ENTITY POST '<command xmlns="http://docbook.org/ns/docbook">POST</command>'>
<!ENTITY DELETE '<command xmlns="http://docbook.org/ns/docbook">DELETE</command>'>
<!ENTITY CHECK '<inlinemediaobject xmlns="http://docbook.org/ns/docbook">
<imageobject role="fo">
<imagedata fileref="figures/Check_mark_23x20_02.svg"
format="SVG" scale="60"/>
</imageobject>
<imageobject role="html">
<imagedata fileref="../figures/Check_mark_23x20_02.png"
format="PNG" />
</imageobject>
</inlinemediaobject>'>
<!ENTITY ARROW '<inlinemediaobject xmlns="http://docbook.org/ns/docbook">
<imageobject role="fo">
<imagedata fileref="figures/Arrow_east.svg"
format="SVG" scale="60"/>
</imageobject>
<imageobject role="html">
<imagedata fileref="../figures/Arrow_east.png"
format="PNG" />
</imageobject>
</inlinemediaobject>'>
]>
<chapter xmlns="http://docbook.org/ns/docbook"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
xml:id="ch_using">
<title>Using Heat</title>
<para>TODO</para>
</chapter>

151
doc/docbkx/heat-admin/pom.xml Normal file
View File

@ -0,0 +1,151 @@
<project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
<modelVersion>4.0.0</modelVersion>
<groupId>org.openstack.docs</groupId>
<artifactId>openstack-guide</artifactId>
<version>1.0.0-SNAPSHOT</version>
<packaging>jar</packaging>
<name>OpenStack Guides</name>
<properties>
<!-- This is set by Jenkins according to the branch. -->
<release.path.name>local</release.path.name>
<comments.enabled>1</comments.enabled>
</properties>
<!-- ################################################ -->
<!-- USE "mvn clean generate-sources" to run this POM -->
<!-- Builds the Heat Administration Manual -->
<!-- ################################################ -->
<profiles>
<profile>
<id>Rackspace Research Repositories</id>
<activation>
<activeByDefault>true</activeByDefault>
</activation>
<repositories>
<repository>
<id>rackspace-research</id>
<name>Rackspace Research Repository</name>
<url>http://maven.research.rackspacecloud.com/content/groups/public/</url>
</repository>
</repositories>
<pluginRepositories>
<pluginRepository>
<id>rackspace-research</id>
<name>Rackspace Research Repository</name>
<url>http://maven.research.rackspacecloud.com/content/groups/public/</url>
</pluginRepository>
</pluginRepositories>
</profile>
</profiles>
<build>
<resources>
<resource>
<directory>target/docbkx/pdf</directory>
<excludes>
<exclude>**/*.fo</exclude>
</excludes>
</resource>
</resources>
<plugins>
<plugin>
<groupId>com.rackspace.cloud.api</groupId>
<artifactId>clouddocs-maven-plugin</artifactId>
<version>1.5.1</version>
<executions>
<execution>
<id>goal1</id>
<goals>
<goal>generate-pdf</goal>
</goals>
<phase>generate-sources</phase>
<configuration>
<highlightSource>false</highlightSource>
<!-- The following elements sets the autonumbering of sections in output for chapter numbers but no numbered sections-->
<sectionAutolabel>0</sectionAutolabel>
<sectionLabelIncludesComponentLabel>0</sectionLabelIncludesComponentLabel>
</configuration>
</execution>
<execution>
<id>goal2</id>
<goals>
<goal>generate-webhelp</goal>
</goals>
<phase>generate-sources</phase>
<configuration>
<!-- These parameters only apply to webhelp -->
<enableDisqus>${comments.enabled}</enableDisqus>
<useVersionForDisqus>1</useVersionForDisqus>
<disqusShortname>os-heat-guides</disqusShortname>
<enableGoogleAnalytics>1</enableGoogleAnalytics>
<googleAnalyticsId>UA-17511903-1</googleAnalyticsId>
<generateToc>
appendix toc,title
article/appendix nop
article toc,title
book title,figure,table,example,equation
chapter toc,title
part toc,title
preface toc,title
qandadiv toc
qandaset toc
reference toc,title
set toc,title
</generateToc>
<!-- The following elements sets the autonumbering of sections in output for chapter numbers but no numbered sections-->
<sectionAutolabel>0</sectionAutolabel>
<sectionLabelIncludesComponentLabel>0</sectionLabelIncludesComponentLabel>
<postProcess>
<!-- Copies the figures to the correct location for webhelp -->
<copy todir="${basedir}/target/docbkx/webhelp/${release.path.name}/heat-admin/content/figures">
<fileset dir="${basedir}/figures">
<include name="**/*.*" />
</fileset>
</copy>
<!-- Copies webhelp (HTML output) to desired URL location on docs.openstack.org -->
<copy
todir="${basedir}/target/docbkx/webhelp/${release.path.name}/heat-admin">
<fileset
dir="${basedir}/target/docbkx/webhelp/bk-heat-admin-guide/">
<include name="**/*" />
</fileset>
</copy>
<!--Moves PDFs to the needed placement -->
<move failonerror="false"
file="${basedir}/target/docbkx/pdf/bk-heat-admin-guide.pdf"
tofile="${basedir}/target/docbkx/webhelp/${release.path.name}/heat-admin/bk-heat-admin-guide-${release.path.name}.pdf"/>
<!--Deletes leftover uneeded directories -->
<delete dir="${basedir}/target/docbkx/webhelp/bk-heat-admin-guide"/>
</postProcess>
</configuration>
</execution>
</executions>
<configuration>
<!-- These parameters apply to pdf and webhelp -->
<xincludeSupported>true</xincludeSupported>
<sourceDirectory>.</sourceDirectory>
<includes>
bk-heat-admin-guide.xml
</includes>
<canonicalUrlBase>http://docs.openstack.org/${release.path.name}/heat-admin/content/</canonicalUrlBase>
<profileSecurity>reviewer</profileSecurity>
<branding>openstack</branding>
</configuration>
</plugin>
</plugins>
</build>
</project>

132
doc/docbkx/heat-cli-guide/pom.xml Normal file
View File

@ -0,0 +1,132 @@
<project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
<modelVersion>4.0.0</modelVersion>
<groupId>org.openstack.docs</groupId>
<artifactId>openstack-cli-guide</artifactId>
<version>1.0.0-SNAPSHOT</version>
<packaging>jar</packaging>
<name>OpenStack CLI Guides</name>
<!-- ################################################ -->
<!-- USE "mvn clean generate-sources" to run this POM -->
<!-- ################################################ -->
<profiles>
<profile>
<id>Rackspace Research Repositories</id>
<activation>
<activeByDefault>true</activeByDefault>
</activation>
<repositories>
<repository>
<id>rackspace-research</id>
<name>Rackspace Research Repository</name>
<url>http://maven.research.rackspacecloud.com/content/groups/public/</url>
</repository>
</repositories>
<pluginRepositories>
<pluginRepository>
<id>rackspace-research</id>
<name>Rackspace Research Repository</name>
<url>http://maven.research.rackspacecloud.com/content/groups/public/</url>
</pluginRepository>
</pluginRepositories>
</profile>
</profiles>
<build>
<resources>
<resource>
<directory>target/docbkx/pdf</directory>
<excludes>
<exclude>**/*.fo</exclude>
</excludes>
</resource>
</resources>
<plugins>
<plugin>
<groupId>com.rackspace.cloud.api</groupId>
<artifactId>clouddocs-maven-plugin</artifactId>
<version>1.5.1</version>
<executions>
<execution>
<id>goal1</id>
<goals>
<goal>generate-pdf</goal>
</goals>
<phase>generate-sources</phase>
<configuration>
<!--<pdfUrl>cli-guide.pdf</pdfUrl>-->
<highlightSource>false</highlightSource>
<!-- The following elements sets the autonumbering of sections in output for chapter numbers but no numbered sections-->
<sectionAutolabel>0</sectionAutolabel>
<sectionLabelIncludesComponentLabel>0</sectionLabelIncludesComponentLabel>
</configuration>
</execution>
<execution>
<id>goal2</id>
<goals>
<goal>generate-webhelp</goal>
</goals>
<phase>generate-sources</phase>
<configuration>
<!-- These parameters only apply to webhelp -->
<pdfUrl>cli-guide.pdf</pdfUrl>
<enableDisqus>1</enableDisqus>
<disqusShortname>os-cliguide</disqusShortname>
<enableGoogleAnalytics>1</enableGoogleAnalytics>
<googleAnalyticsId>UA-17511903-1</googleAnalyticsId>
<generateToc>
appendix toc,title
article/appendix nop
article toc,title
book title,figure,table,example,equation
chapter toc,title
part toc,title
preface toc,title
qandadiv toc
qandaset toc
reference toc,title
set toc,title
</generateToc>
<!-- The following elements sets the autonumbering of sections in output for chapter numbers but no numbered sections-->
<sectionAutolabel>0</sectionAutolabel>
<sectionLabelIncludesComponentLabel>0</sectionLabelIncludesComponentLabel>
<postProcess>
<!-- Copies webhelp (HTML output) to desired URL location on docs.openstack.org -->
<copy
todir="${basedir}/target/docbkx/webhelp/cli-guide/">
<fileset
dir="${basedir}/target/docbkx/webhelp/bk-cli-guide/">
<include name="**/*" />
</fileset>
</copy>
<!--Moves PDF to the needed placement -->
<move failonerror="false"
file="${basedir}/target/docbkx/pdf/bk-cli-guide.pdf"
tofile="${basedir}/target/docbkx/webhelp/cli-guide/content/cli-guide.pdf"/>
<!--Deletes leftover uneeded directories -->
<delete dir="${basedir}/target/docbkx/webhelp/bk-cli-guide"/>
</postProcess>
</configuration>
</execution>
</executions>
<configuration>
<!-- These parameters apply to pdf and webhelp -->
<xincludeSupported>true</xincludeSupported>
<sourceDirectory>src</sourceDirectory>
<includes>
bk-cli-guide.xml
</includes>
<!--<canonicalUrlBase>http://docs.openstack.org/cli/content/</canonicalUrlBase>-->
<profileSecurity>reviewer</profileSecurity>
<branding>openstack</branding>
</configuration>
</plugin>
</plugins>
</build>
</project>

15
doc/docbkx/heat-cli-guide/src/bk-cli-guide.xml Normal file
View File

@ -0,0 +1,15 @@
<?xml version="1.0" encoding="UTF-8"?>
<chapter xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:svg="http://www.w3.org/2000/svg"
xmlns:html="http://www.w3.org/1999/xhtml" version="5.0"
xml:id="openstack-cli-guide-trunk">
<title>OpenStack CLI Guide</title>
<para>Each OpenStack project has a Command-Line-Interface (CLI)
that interacts with the service's REST API. </para>
<xi:include href="heat_cli_install.xml"/>
<xi:include href="heat_cli_commands.xml"/>
<xi:include href="heat_cli_howto.xml"/>
</chapter>

22
doc/docbkx/heat-cli-guide/src/heat_cli_commands.xml Normal file
View File

@ -0,0 +1,22 @@
<?xml version="1.0" encoding="UTF-8"?>
<section xmlns="http://docbook.org/ns/docbook"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
xml:id="heat_client_commands">
<title>Command List for heat CLI</title>
<literallayout class="monospaced">
event-list List events for a stack
event-show Describe the event
resource-list Show list of resources belonging to a stack
resource-metadata List resource metadata
resource-show Describe the resource
stack-create Create the stack
stack-delete Delete the stack
stack-list List the user's stacks
stack-show Describe the stack
stack-update Update the stack
template-show Get the template for the specified stack
template-validate Validate a template with parameters
help Display help about this program or one of its subcommands.
</literallayout>
</section>

13
doc/docbkx/heat-cli-guide/src/heat_cli_howto.xml Normal file
View File

@ -0,0 +1,13 @@
<?xml version="1.0" encoding="UTF-8"?>
<section xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:svg="http://www.w3.org/2000/svg"
xmlns:html="http://www.w3.org/1999/xhtml"
version="5.0"
xml:id="quantum-cli-reference">
<?dbhtml stop-chunking?>
<title>OpenStack Heat CLI Guide</title>
<para>This section describes heat commands</para>
</section>

84
doc/docbkx/heat-cli-guide/src/heat_cli_install.xml Normal file
View File

@ -0,0 +1,84 @@
<?xml version="1.0" encoding="UTF-8"?>
<section xmlns="http://docbook.org/ns/docbook"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
xml:id="install_openstack_heat_cli">
<title>Install OpenStack heat CLI</title>
<para>This example walks through installing the heat client. After
you install a client, you must configure environment variables
for authentication. </para>
<procedure>
<title>To install the heat client:</title>
<step>
<title>Install Python</title>
<para>Install Python 2.6 or later. Currently, the heat
client does not support Python 3. </para>
</step>
<step>
<title>Install the heat client package</title>
<para>Choose one of the following methods to install the
heat client package. <itemizedlist>
<listitem>
<para><emphasis role="bold">Recommended
method:</emphasis>
<command>pip</command></para>
<para>Install <command>pip</command> through
the package manager for your
system:<informaltable rules="all">
<col width="20%"/>
<col width="80%"/>
<thead>
<tr>
<th>System</th>
<th>Command</th>
</tr>
</thead>
<tbody>
<tr>
<td>Mac OS X</td>
<td>
<programlisting language="bash" role="gutter: false"><prompt>$</prompt> sudo easy_install pip</programlisting>
</td>
</tr>
<tr>
<td>Ubuntu</td>
<td>
<programlisting language="bash" role="gutter: false"><prompt>$</prompt> aptitude install python-pip </programlisting>
</td>
</tr>
<tr>
<td>RHEL, CentOS, or Fedora:</td>
<td>
<programlisting language="bash" role="gutter: false"><prompt>$</prompt> yum install python-pip</programlisting>
</td>
</tr>
</tbody>
</informaltable></para>
<para>Run the following command to install the heat client package:
<programlisting language="bash" role="gutter: false"><prompt>$</prompt> sudo pip install python-heatclient</programlisting></para>
</listitem>
<listitem>
<para><emphasis role="bold"
>easy_install</emphasis></para>
<para>Run the following command to install the
heat client package: </para>
<programlisting language="bash" role="gutter: false"><prompt>$</prompt> sudo easy_install python-heatclient</programlisting>
</listitem>
</itemizedlist></para>
</step>
<step>
<title>Get help for heat client commands</title>
<para>To get help for heat client commands, run the
following command:</para>
<programlisting language="bash" role="gutter: false"><prompt>$</prompt> heat -h </programlisting>
<para>Depending on your user credentials, you may not have
permissions to use every command that is listed. The
heat client was written for use with recent
development versions of OpenStack.</para>
<para>To get help for a specific command, type the command
name after the <parameter>help</parameter> parameter,
as follows:</para>
<programlisting language="bash" role="gutter: false"><prompt>$</prompt> heat help &lt;command_name&gt; </programlisting>
</step>
</procedure></section>

259
doc/source/conf.py Normal file
View File

@ -0,0 +1,259 @@
# -*- coding: utf-8 -*-
#
# Heat documentation build configuration file, created by
# sphinx-quickstart on Thu Dec 13 11:23:35 2012.
#
# This file is execfile()d with the current directory set to its containing
# dir.
#
# Note that not all possible configuration values are present in this
# autogenerated file.
#
# All configuration values have a default; values that are commented out
# serve to show the default.
import os
import sys
# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
sys.path.insert(0, os.path.abspath('../../'))
# -- General configuration ----------------------------------------------------
# If your documentation needs a minimal Sphinx version, state it here.
#needs_sphinx = '1.0'
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
extensions = ['sphinx.ext.autodoc',
'sphinx.ext.ifconfig',
'sphinx.ext.viewcode']
# Add any paths that contain templates here, relative to this directory.
#templates_path = ['_templates']
# The suffix of source filenames.
source_suffix = '.rst'
# The encoding of source files.
#source_encoding = 'utf-8-sig'
# The master toctree document.
master_doc = 'index'
# General information about the project.
project = u'Heat'
copyright = u'2012, Heat Developers'
# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
# built documents.
from heat.version import version_info as heat_version
release = heat_version.version_string_with_vcs()
version = heat_version.canonical_version_string()
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
#language = None
# There are two options for replacing |today|: either, you set today to some
# non-false value, then it is used:
#today = ''
# Else, today_fmt is used as the format for a strftime call.
#today_fmt = '%B %d, %Y'
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
exclude_patterns = []
# The reST default role (used for this markup: `text`) to use for all
# documents.
#default_role = None
# If true, '()' will be appended to :func: etc. cross-reference text.
#add_function_parentheses = True
# If true, the current module name will be prepended to all description
# unit titles (such as .. function::).
#add_module_names = True
# If true, sectionauthor and moduleauthor directives will be shown in the
# output. They are ignored by default.
#show_authors = False
# The name of the Pygments (syntax highlighting) style to use.
pygments_style = 'sphinx'
# A list of ignored prefixes for module index sorting.
#modindex_common_prefix = []
# -- Options for HTML output --------------------------------------------------
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
html_theme = 'default'
# Theme options are theme-specific and customize the look and feel of a theme
# further. For a list of options available for each theme, see the
# documentation.
#html_theme_options = {}
# Add any paths that contain custom themes here, relative to this directory.
#html_theme_path = []
# The name for this set of Sphinx documents. If None, it defaults to
# "<project> v<release> documentation".
#html_title = None
# A shorter title for the navigation bar. Default is the same as html_title.
#html_short_title = None
# The name of an image file (relative to this directory) to place at the top
# of the sidebar.
#html_logo = None
# The name of an image file (within the static path) to use as favicon of the
# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
# pixels large.
#html_favicon = None
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
#html_static_path = ['_static']
# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
# using the given strftime format.
#html_last_updated_fmt = '%b %d, %Y'
# If true, SmartyPants will be used to convert quotes and dashes to
# typographically correct entities.
#html_use_smartypants = True
# Custom sidebar templates, maps document names to template names.
#html_sidebars = {}
# Additional templates that should be rendered to pages, maps page names to
# template names.
#html_additional_pages = {}
# If false, no module index is generated.
#html_domain_indices = True
# If false, no index is generated.
#html_use_index = True
# If true, the index is split into individual pages for each letter.
#html_split_index = False
# If true, links to the reST sources are added to the pages.
#html_show_sourcelink = True
# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
#html_show_sphinx = True
# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
#html_show_copyright = True
# If true, an OpenSearch description file will be output, and all pages will
# contain a <link> tag referring to it. The value of this option must be the
# base URL from which the finished HTML is served.
#html_use_opensearch = ''
# This is the file name suffix for HTML files (e.g. ".xhtml").
#html_file_suffix = None
# Output file base name for HTML help builder.
htmlhelp_basename = 'Heatdoc'
# -- Options for LaTeX output -------------------------------------------------
latex_elements = {
# The paper size ('letterpaper' or 'a4paper').
#'papersize': 'letterpaper',
# The font size ('10pt', '11pt' or '12pt').
#'pointsize': '10pt',
# Additional stuff for the LaTeX preamble.
#'preamble': '',
}
# Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title, author, documentclass [howto/manual])
latex_documents = [
('index', 'Heat.tex', u'Heat Documentation',
u'Heat Developers', 'manual'),
]
# The name of an image file (relative to this directory) to place at the top of
# the title page.
#latex_logo = None
# For "manual" documents, if this is true, then toplevel headings are parts,
# not chapters.
#latex_use_parts = False
# If true, show page references after internal links.
#latex_show_pagerefs = False
# If true, show URL addresses after external links.
#latex_show_urls = False
# Documents to append as an appendix to all manuals.
#latex_appendices = []
# If false, no module index is generated.
#latex_domain_indices = True
# -- Options for manual page output -------------------------------------------
# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
man_pages = [
('man/heat-cfn', 'heat-cfn',
u'Command line utility to run heat actions over the CloudFormation API',
[u'Heat Developers'], 1),
('man/heat-api', 'heat-api',
u'REST API service to the heat project.',
[u'Heat Developers'], 1),
('man/heat-api-cfn', 'heat-api-cfn',
u'CloudFormation compatible API service to the heat project.',
[u'Heat Developers'], 1),
('man/heat-api-cloudwatch', 'heat-api-cloudwatch',
u'CloudWatch alike API service to the heat project',
[u'Heat Developers'], 1),
('man/heat-engine', 'heat-engine',
u'Service which performs the actions from the API calls made by the user',
[u'Heat Developers'], 1)
]
# If true, show URL addresses after external links.
#man_show_urls = False
# -- Options for Texinfo output -----------------------------------------------
# Grouping the document tree into Texinfo files. List of tuples
# (source start file, target name, title, author,
# dir menu entry, description, category)
texinfo_documents = [
('index', 'Heat', u'Heat Documentation',
u'Heat Developers', 'Heat', 'One line description of project.',
'Miscellaneous'),
]
# Documents to append as an appendix to all manuals.
#texinfo_appendices = []
# If false, no module index is generated.
#texinfo_domain_indices = True
# How to display URL addresses: 'footnote', 'no', or 'inline'.
#texinfo_show_urls = 'footnote'

25
doc/source/index.rst Normal file
View File

@ -0,0 +1,25 @@
.. Heat documentation master file, created by
sphinx-quickstart on Thu Dec 13 11:23:35 2012.
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.
Welcome to the Heat developer documentation!
================================
This documentation offers information on how Heat works and how to contribute to the project.
Contents:
.. toctree::
:maxdepth: 2
GettingStarted.rst
man/index
Indices and tables
==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

40
doc/source/man/heat-api-cfn.rst Normal file
View File

@ -0,0 +1,40 @@
============
heat-api-cfn
============
.. program:: heat-api-cfn
SYNOPSIS
========
``heat-api-cfn [options]``
DESCRIPTION
===========
heat-api-cfn is a CloudFormation compatible API service to the heat project.
INVENTORY
=========
heat-api-cfn is a service that exposes an external REST based api to the
heat-engine service. The communication between the heat-api-cfn and
heat-engine uses message queue based RPC.
OPTIONS
=======
.. cmdoption:: --config-file
Path to a config file to use. Multiple config files can be specified, with
values in later files taking precedence.
.. cmdoption:: --config-dir
Path to a config directory to pull .conf files from. This file set is
sorted, so as to provide a predictable parse order if individual options are
over-ridden. The set is parsed after the file(s), if any, specified via
--config-file, hence over-ridden options in the directory take precedence.
FILES
========
* /etc/heat/heat-api-cfn.conf
* /etc/heat/heat-api-cfn-paste.ini

34
doc/source/man/heat-api-cloudwatch.rst Normal file
View File

@ -0,0 +1,34 @@
===================
heat-api-cloudwatch
===================
.. program:: heat-api-cloudwatch
SYNOPSIS
========
``heat-api-cloudwatch [options]``
DESCRIPTION
===========
heat-api-cloudwatch is a CloudWatch alike API service to the heat project
OPTIONS
=======
.. cmdoption:: --config-file
Path to a config file to use. Multiple config files can be specified, with
values in later files taking precedence.
.. cmdoption:: --config-dir
Path to a config directory to pull .conf files from. This file set is
sorted, so as to provide a predictable parse order if individual options are
over-ridden. The set is parsed after the file(s), if any, specified via
--config-file, hence over-ridden options in the directory take precedence.
FILES
========
* /etc/heat/heat-api-cloudwatch.conf
* /etc/heat/heat-api-cloudwatch-paste.ini

40
doc/source/man/heat-api.rst Normal file
View File

@ -0,0 +1,40 @@
========
heat-api
========
.. program:: heat-api
SYNOPSIS
========
``heat-api [options]``
DESCRIPTION
===========
heat-api provides an external REST API to the heat project.
INVENTORY
=========
heat-api is a service that exposes an external REST based api to the
heat-engine service. The communication between the heat-api
heat-engine uses message queue based RPC.
OPTIONS
=======
.. cmdoption:: --config-file
Path to a config file to use. Multiple config files can be specified, with
values in later files taking precedence.
.. cmdoption:: --config-dir
Path to a config directory to pull .conf files from. This file set is
sorted, so as to provide a predictable parse order if individual options are
over-ridden. The set is parsed after the file(s), if any, specified via
--config-file, hence over-ridden options in the directory take precedence.
FILES
========
* /etc/heat/heat-api.conf
* /etc/heat/heat-api-paste.ini

199
doc/source/man/heat-cfn.rst Normal file
View File

@ -0,0 +1,199 @@
========
heat-cfn
========
.. program:: heat-cfn
SYNOPSIS
========
``heat-cfn [OPTIONS] COMMAND [COMMAND_OPTIONS]``
DESCRIPTION
===========
heat-cfn is a command-line utility for heat. It is simply an
interface for adding, modifying, and retrieving information about the stacks
belonging to a user. It is a convenience application that talks to the heat
CloudFormation API compatable server.
CONFIGURATION
=============
heat-cfn uses keystone authentication, and expects some variables to be
set in your environment, without these heat will not be able to establish
an authenticated connection with the heat API server.
Example:
export ADMIN_TOKEN=<keystone admin token>
export OS_USERNAME=admin
export OS_PASSWORD=verybadpass
export OS_TENANT_NAME=admin
export OS_AUTH_URL=http://127.0.0.1:5000/v2.0/
export OS_AUTH_STRATEGY=keystone
COMMANDS
========
``create``
Create stack as defined in template file
``delete``
Delete specified stack
``describe``
Provide detailed information about the specified stack, or if no arguments are given all stacks
``estimate-template-cost``
Currently not implemented
``event-list``
List events related to specified stacks, or if no arguments are given all stacks
``gettemplate``
Get the template for a running stack
``help``
Provide help/usage information
``list``
List summary information for all stacks
``resource``
List information about a specific resource
``resource-list``
List all resources for a specified stack
``resource-list-details``
List details of all resources for a specified stack or physical resource ID, optionally filtered by a logical resource ID
``update``
Update a running stack with a modified template or template parameters - currently not implemented
``validate``
Validate a template file syntax
OPTIONS
=======
.. cmdoption:: -S, --auth_strategy
Authentication strategy
.. cmdoption:: -A, --auth_token
Authentication token to use to identify the client to the heat server
.. cmdoption:: -N, --auth_url
Authentication URL for keystone authentication
.. cmdoption:: -d, --debug
Enable verbose debug level output
.. cmdoption:: -H, --host
Specify the hostname running the heat API service
.. cmdoption:: -k, --insecure
Use plain HTTP instead of HTTPS
.. cmdoption:: -P, --parameters
Stack input parameters
.. cmdoption:: -K, --password
Password used to acquire an authentication token
.. cmdoption:: -p, --port
Specify the port to connect to for the heat API service
.. cmdoption:: -R, --region
Region name. When using keystone authentication "version 2.0 or later this identifies the region
.. cmdoption:: -f, --template-file
Path to file containing the stack template
.. cmdoption:: -u, --template-url
URL to stack template
.. cmdoption:: -T, --tenant
Tenant name used for Keystone authentication
.. cmdoption:: -t, --timeout
Stack creation timeout (default is 60 minutes)
.. cmdoption:: -U, --url
URL of heat service
.. cmdoption:: -I, --username
User name used to acquire an authentication token
.. cmdoption:: -v, --verbose
Enable verbose output
.. cmdoption:: -y, --yes
Do not prompt for confirmation, assume yes
EXAMPLES
========
heat-cfn -d create wordpress --template-
file=templates/WordPress_Single_Instance.template
--parameters="InstanceType=m1.xlarge;DBUsername=${USER};DBPassword=verybadpass;KeyName=${USER}_key"
heat-cfn list
heat-cfn describe wordpress
heat-cfn resource-list wordpress
heat-cfn resource-list-details wordpress
heat-cfn resource-list-details wordpress WikiDatabase
heat-cfn resource wordpress WikiDatabase
heat-cfn event-list
heat-cfn delete wordpress
BUGS
====
Heat bugs are managed through Launchpad <https://launchpad.net/heat>

38
doc/source/man/heat-engine.rst Normal file
View File

@ -0,0 +1,38 @@
===========
heat-engine
===========
.. program:: heat-api-engine
SYNOPSIS
========
``heat-engine [options]``
DESCRIPTION
===========
Heat is the heat project server with an internal api called by the heat-api.
INVENTORY
=========
The heat engine does all the orchestration work and is the layer in which
the resource integration is implemented.
OPTIONS
=======
.. cmdoption:: --config-file
Path to a config file to use. Multiple config files can be specified, with
values in later files taking precedence.
.. cmdoption:: --config-dir
Path to a config directory to pull .conf files from. This file set is
sorted, so as to provide a predictable parse order if individual options are
over-ridden. The set is parsed after the file(s), if any, specified via
--config-file, hence over-ridden options in the directory take precedence.
FILES
========
* /etc/heat/heat-engine.conf

24
doc/source/man/index.rst Normal file
View File

@ -0,0 +1,24 @@
===================================
Man pages for services and utilities
===================================
-------------
Heat services
-------------
.. toctree::
:maxdepth: 2
heat-engine
heat-api
heat-api-cfn
heat-api-cloudwatch
--------------
Heat utilities
--------------
.. toctree::
:maxdepth: 2
heat-cfn

43
docs/man/man1/heat-api-cfn.1
View File

@ -1,43 +0,0 @@
'\" t
.\" Title: heat
.\" Author: [see the "AUTHOR" section]
.\" Generator: DocBook XSL Stylesheets v1.75.2 <http://docbook.sf.net/>
.\" Date: 03/31/2012
.\" Manual: System administration commands
.\" Source: Heat 0.0.1
.\" Language: English
.\"
.TH "HEAT" "1" "03/31/2012" "HEAT 0\&.0\&.1" "System administration commands"
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
heat-api-cfn \- The external api to the heat engine
.SH "SYNOPSIS"
.sp
heat-engine
.SH "DESCRIPTION"
.sp
\fBHeat\fR is the external api to the heat project\&.
.RE
.PP
.SH "INVENTORY"
.sp
The heat api is a services that exposes an external api to the heat-engine service. The communication between the heat-api and heat-engine uses RPC\&.
.SH "AUTHOR"
.sp
See the AUTHORS file for a complete list of contributors\&.
.SH "COPYRIGHT"
.sp
Copyright \(co 2012, Red Hat Inc
.sp
Heat is released under the terms of the ASL 2 License\&.
.sp
Extensive documentation as well as IRC and mailing list info is available on the heat home page: http://heat\&-api\&.org/

198
docs/man/man1/heat-boto.1
View File

@ -1,198 +0,0 @@
'\" t
.\" Title: heat-boto
.\" Author: [see the "AUTHOR" section]
.\" Generator: DocBook XSL Stylesheets v1.75.2 <http://docbook.sf.net/>
.\" Date: 03/31/2012
.\" Manual: System administration commands
.\" Source: Heat 0.0.1
.\" Language: English
.\"
.TH "HEAT" "1" "03/31/2012" "HEAT 0\&.0\&.1" "System administration commands"
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
heat-boto \- perform a heat action via the heat API
.SH "SYNOPSIS"
.sp
heat-boto COMMAND [OPTIONS]
.SH "DESCRIPTION"
.sp
\fBheat-boto\fR is a tool to orchestrate the setup of multiple cloud applications\&.
\fBheat-boto\fR is port a of the \fBheat\fR tool to use the boto client library\&.
.SH CONFIGURATION FILES
heat-boto uses the boto client library, which looks for configuration in /etc/boto.cfg
heat installs a default version of this file, but you will need to update the
aws_access_key_id and aws_secret_access_key values with your real keystone credentials\&.
Use keystone ec2-credentials-list to retrieve your keystone ec2 access keys\&.
.SH "COMMANDS"
.PP
\fBcreate\fP
.RS 4
Create stack as defined in template file
.RE
.PP
\fBdelete\fP
.RS 4
Delete specified stack
.RE
.PP
\fBdescribe\fP
.RS 4
Provide detailed information about the specified stack, or if no arguments are given all stacks
.RE
.PP
\fBestimate-template-cost\fP
.RS 4
Currently not implemented
.RE
.PP
\fBevent-list\fP
.RS 4
List events related to specified stacks, or if no arguments are given all stacks
.RE
.PP
\fBgettemplate\fP
.RS 4
Get the template for a running stack
.RE
.PP
\fBhelp\fP
.RS 4
Provide help/usage information
.RE
.PP
\fBlist\fP
.RS 4
List summary information for all stacks
.RE
.PP
\fBresource\fP
.RS 4
List information about a specific resource
.RE
.PP
\fBresource-list\fP
.RS 4
List all resources for a specified stack
.RE
.PP
\fBresource-list-details\fP
.RS 4
List details of all resources for a specified stack or physical resource ID, optionally filtered by a logical resource ID
.RE
.PP
\fBupdate\fP
.RS 4
Update a running stack with a modified template or template parameters - currently not implemented
.RE
.PP
\fBvalidate\fP
.RS 4
Validate a template file syntax
.RE
.SH "OPTIONS"
.PP
\fB\-d\fR, \fB\-\-debug\fR
.RS 4
Enable verbose debug level output
.RE
.PP
\fB\-H\fR, \fB\-\-host\fR
.RS 4
Specify the hostname running the heat API service
.RE
.PP
\fB\-k\fR, \fB\-\-insecure\fR
.RS 4
Use plain HTTP instead of HTTPS
.RE
.PP
\fB\-P\fR, \fB\-\-parameters\fR
.RS 4
Stack input parameters
.RE
.PP
\fB\-p\fR, \fB\-\-port\fR
.RS 4
Specify the port to connect to for the heat API service
.RE
.PP
\fB\-R\fR, \fB\-\-region\fR
.RS 4
Region name. When using keystone authentication "version 2.0 or later this identifies the region
.RE
.PP
\fB\-f\fR, \fB\-\-template\fR-file
.RS 4
Path to file containing the stack template
.RE
.PP
\fB\-u\fR, \fB\-\-template\fR-url
.RS 4
URL to stack template
.RE
.PP
\fB\-t\fR, \fB\-\-timeout\fR
.RS 4
Stack creation timeout (default is 60 minutes)
.RE
.PP
\fB\-v\fR, \fB\-\-verbose\fR
.RS 4
Enable verbose output
.RE
.PP
\fB\-y\fR, \fB\-\-yes\fR
.RS 4
Do not prompt for confirmation, assume yes
.RE
.PP
.SH "USAGE EXAMPLES"
.sp
heat-boto -d create wordpress --template-file=templates/WordPress_Single_Instance.template --parameters="InstanceType=m1.xlarge;DBUsername=${USER};DBPassword=verybadpass;KeyName=${USER}_key"
heat-boto list
heat-boto describe wordpress
heat-boto resource-list wordpress
heat-boto resource-list-details wordpress
heat-boto resource-list-details wordpress WikiDatabase
heat-boto resource wordpress WikiDatabase
heat-boto event-list
heat-boto delete wordpress
.SH "AUTHOR"
.sp
See the AUTHORS file for a complete list of contributors\&.
.SH "COPYRIGHT"
.sp
Copyright \(co 2012, Red Hat Inc
.sp
Heat is released under the terms of the ASL 2 License\&.
.sp
Extensive documentation as well as IRC and mailing list info is available on the heat home page: https://heat\&-api\&.org/

243
docs/man/man1/heat-cfn.1
View File

@ -1,243 +0,0 @@
'\" t
.\" Title: heat-cfn
.\" Author: [see the "AUTHOR" section]
.\" Generator: DocBook XSL Stylesheets v1.75.2 <http://docbook.sf.net/>
.\" Date: 03/31/2012
.\" Manual: System administration commands
.\" Source: Heat 0.0.1
.\" Language: English
.\"
.TH "HEAT" "1" "03/31/2012" "HEAT 0\&.0\&.1" "System administration commands"
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
heat-cfn \- perform a heat action via the heat API
.SH "SYNOPSIS"
.sp
heat-cfn COMMAND [OPTIONS]
.SH "DESCRIPTION"
.sp
\fBheat-cfn\fR is a tool to orchestrate the setup of multiple cloud applications\&.
.SH CONFIGURATION
heat-cfn uses keystone authentication, and expects some variables to be set in
your environment, without these heat will not be able to establish an
authenticated connection with the heat API server.
Example:
.br
export ADMIN_TOKEN=<keystone admin token>
.br
export OS_USERNAME=admin
.br
export OS_PASSWORD=verybadpass
.br
export OS_TENANT_NAME=admin
.br
export OS_AUTH_URL=http://127.0.0.1:5000/v2.0/
.br
export OS_AUTH_STRATEGY=keystone
.br
.SH "COMMANDS"
.PP
\fBcreate\fP
.RS 4
Create stack as defined in template file
.RE
.PP
\fBdelete\fP
.RS 4
Delete specified stack
.RE
.PP
\fBdescribe\fP
.RS 4
Provide detailed information about the specified stack, or if no arguments are given all stacks
.RE
.PP
\fBestimate-template-cost\fP
.RS 4
Currently not implemented
.RE
.PP
\fBevent-list\fP
.RS 4
List events related to specified stacks, or if no arguments are given all stacks
.RE
.PP
\fBgettemplate\fP
.RS 4
Get the template for a running stack
.RE
.PP
\fBhelp\fP
.RS 4
Provide help/usage information
.RE
.PP
\fBlist\fP
.RS 4
List summary information for all stacks
.RE
.PP
\fBresource\fP
.RS 4
List information about a specific resource
.RE
.PP
\fBresource-list\fP
.RS 4
List all resources for a specified stack
.RE
.PP
\fBresource-list-details\fP
.RS 4
List details of all resources for a specified stack or physical resource ID, optionally filtered by a logical resource ID
.RE
.PP
\fBupdate\fP
.RS 4
Update a running stack with a modified template or template parameters - currently not implemented
.RE
.PP
\fBvalidate\fP
.RS 4
Validate a template file syntax
.RE
.SH "OPTIONS"
.PP
\fB\-S\fR, \fB\-\-auth_strategy\fR
.RS 4
Authentication strategy
.RE
.PP
\fB\-A\fR, \fB\-\-auth_token\fR
.RS 4
Authentication token to use to identify the client to the heat server
.RE
.PP
\fB\-N\fR, \fB\-\-auth_url\fR
.RS 4
Authentication URL for keystone authentication
.RE
.PP
\fB\-d\fR, \fB\-\-debug\fR
.RS 4
Enable verbose debug level output
.RE
.PP
\fB\-H\fR, \fB\-\-host\fR
.RS 4
Specify the hostname running the heat API service
.RE
.PP
\fB\-k\fR, \fB\-\-insecure\fR
.RS 4
Use plain HTTP instead of HTTPS
.RE
.PP
\fB\-P\fR, \fB\-\-parameters\fR
.RS 4
Stack input parameters
.RE
.PP
\fB\-K\fR, \fB\-\-password\fR
.RS 4
Password used to acquire an authentication token
.RE
.PP
\fB\-p\fR, \fB\-\-port\fR
.RS 4
Specify the port to connect to for the heat API service
.RE
.PP
\fB\-R\fR, \fB\-\-region\fR
.RS 4
Region name. When using keystone authentication "version 2.0 or later this identifies the region
.RE
.PP
\fB\-f\fR, \fB\-\-template\fR-file
.RS 4
Path to file containing the stack template
.RE
.PP
\fB\-u\fR, \fB\-\-template\fR-url
.RS 4
URL to stack template
.RE
.PP
\fB\-T\fR, \fB\-\-tenant\fR
.RS 4
Tenant name used for Keystone authentication
.RE
.PP
\fB\-t\fR, \fB\-\-timeout\fR
.RS 4
Stack creation timeout (default is 60 minutes)
.RE
.PP
\fB\-U\fR, \fB\-\-url\fR
.RS 4
URL of heat service
.RE
.PP
\fB\-I\fR, \fB\-\-username\fR
.RS 4
User name used to acquire an authentication token
.RE
.PP
\fB\-v\fR, \fB\-\-verbose\fR
.RS 4
Enable verbose output
.RE
.PP
\fB\-y\fR, \fB\-\-yes\fR
.RS 4
Do not prompt for confirmation, assume yes
.RE
.PP
.SH "USAGE EXAMPLES"
.sp
heat-cfn -d create wordpress --template-file=templates/WordPress_Single_Instance.template --parameters="InstanceType=m1.xlarge;DBUsername=${USER};DBPassword=verybadpass;KeyName=${USER}_key"
heat-cfn list
heat-cfn describe wordpress
heat-cfn resource-list wordpress
heat-cfn resource-list-details wordpress
heat-cfn resource-list-details wordpress WikiDatabase
heat-cfn resource wordpress WikiDatabase
heat-cfn event-list
heat-cfn delete wordpress
.SH "AUTHOR"
.sp
See the AUTHORS file for a complete list of contributors\&.
.SH "COPYRIGHT"
.sp
Copyright \(co 2012, Red Hat Inc
.sp
Heat is released under the terms of the ASL 2 License\&.
.sp
Extensive documentation as well as IRC and mailing list info is available on the heat home page: https://heat\&-api\&.org/

77
docs/man/man1/heat-db-setup.1
View File

@ -1,77 +0,0 @@
'\" t
.\" Title: heat
.\" Author: [see the "AUTHOR" section]
.\" Generator: DocBook XSL Stylesheets v1.75.2 <http://docbook.sf.net/>
.\" Date: 03/31/2012
.\" Manual: System administration commands
.\" Source: Heat 0.0.1
.\" Language: English
.\"
.TH "HEAT" "1" "06/13/2012" "HEAT 0\&.0\&.1" "System administration commands"
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
heat-db-setup \- Setup and configure the Heat database
.SH "SYNOPSIS"
.sp
heat-db-setup <platform_type>
.SH "DESCRIPTION"
.sp
The \fBheat-db-setup\fR script creates the heat database on the system,
using MYSQL as a backend database. The script works on either RPM or DEB
based distributions. If the MYSQL server is not present, the user will
be prompted to install it. If the MYSQL server is not running, the user
will be prompted to start it. Once MYSQL is started, the appropriate
SQL commands will be run to instantiate the database on the system.
.SH "OPTIONS"
.PP
\fB\platform_type\fR
.RS 4
This required option can be either rpm or deb, which will use the appropriate
platform specific tools and packaging to instantiate the database.
.PP
\fB\--help\fR
.RS 4
Print usage information.
.PP
\fB\--password <pw>\fR
.RS 4
Specify the password for the 'heat' MySQL user that will use to connect to
the 'heat' MySQL database. By default, the password 'heat' will be used.
.PP
\fB\--yes\fR
.RS 4
In cases where the script would normally ask for confirmation before doing
something, such as installing mysql-server, just assume yes. This is useful
if you want to run the script non-interactively.
.SH "BUGS"
.sp
Since Heat is in active development, occasionally the database may suffer
corruption during master updates. In this case, the heat-db-drop tool can
be used to drop the database tables and start from scratch. This application
is only shipped in the source tarball, since it will be unnecessary when Heat
is production quality and too heavyweight for a production deployment.
.SH "AUTHOR"
.sp
See the AUTHORS file for a complete list of contributors\&.
.SH "COPYRIGHT"
.sp
Copyright \(co 2012, Red Hat Inc
.sp
Heat is released under the terms of the ASL 2 License\&.
.sp
Extensive documentation as well as IRC and mailing list info is available on the heat home page: https://heat\&-api\&.org/

43
docs/man/man1/heat-engine.1
View File

@ -1,43 +0,0 @@
'\" t
.\" Title: heat
.\" Author: [see the "AUTHOR" section]
.\" Generator: DocBook XSL Stylesheets v1.75.2 <http://docbook.sf.net/>
.\" Date: 03/31/2012
.\" Manual: System administration commands
.\" Source: Heat 0.0.1
.\" Language: English
.\"
.TH "HEAT" "1" "03/31/2012" "HEAT 0\&.0\&.1" "System administration commands"
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
heat-engine \- The heat engine
.SH "SYNOPSIS"
.sp
heat-engine
.SH "DESCRIPTION"
.sp
\fBHeat\fR is the heat project server with an internal api called by the heat-api\&.
.RE
.PP
.SH "INVENTORY"
.sp
The heat engine does all the orchestration work and is the layer in which the resource integration is implemented\&.
.SH "AUTHOR"
.sp
See the AUTHORS file for a complete list of contributors\&.
.SH "COPYRIGHT"
.sp
Copyright \(co 2012, Red Hat Inc
.sp
Heat is released under the terms of the ASL 2 License\&.
.sp
Extensive documentation as well as IRC and mailing list info is available on the heat home page: http://heat\&-api\&.org/