Skip to content

Commit

Permalink
A new documention structure, ready for contributions
Browse files Browse the repository at this point in the history 
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
  • Loading branch information
@steveb
steveb committed Dec 18, 2012
1 parent 083c0cc commit c477779
Show file tree
Hide file tree
Showing 33 changed files with 1,729 additions and 604 deletions.
2 changes: 2 additions & 0 deletions doc/.gitignore
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
target/
build/
153 changes: 153 additions & 0 deletions doc/Makefile
View file
Original file line number Diff line number Diff line change
@@ -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 changes: 35 additions & 0 deletions doc/README.rst
View file
Original file line number Diff line number Diff line change
@@ -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 changes: 35 additions & 0 deletions doc/docbkx/README.rst
View file
Original file line number Diff line number Diff line change
@@ -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 changes: 76 additions & 0 deletions doc/docbkx/api-ref/pom.xml
View file
Original file line number Diff line number Diff line change
@@ -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 changes: 24 additions & 0 deletions doc/docbkx/api-ref/src/docbkx/api-ref.xml
View file
Original file line number Diff line number Diff line change
@@ -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 changes: 13 additions & 0 deletions doc/docbkx/api-ref/src/wadls/heat-api/src/heat-api-1.0.wadl
View file
Original file line number Diff line number Diff line change
@@ -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 changes: 16 additions & 0 deletions doc/docbkx/heat-admin/app_core.xml
View file
Original file line number Diff line number Diff line change
@@ -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>
Loading

0 comments on commit c477779

Please sign in to comment.