Merge pull request #199 from behdad/travis-docs

Deploy docs to gh-pages branch from Travis builds

.ci/deploy-docs.sh

@@ -0,0 +1,25 @@
+set -o errexit -o nounset
+
+if [ "$TRAVIS_OS_NAME" == "linux" -a "$CC" == "gcc" -a "$TRAVIS_PULL_REQUEST" == "false" -a "$TRAVIS_BRANCH" == "master" ]
+then
+	DOCSDIR=build-docs
+	REVISION=$(git rev-parse --short HEAD)
+
+	rm -rf $DOCSDIR || exit
+	mkdir $DOCSDIR
+	cd $DOCSDIR
+
+	cp ../docs/html/* .
+
+	git init
+	git config user.name "Travis CI"
+	git config user.email "travis@harfbuzz.org"
+	git remote add upstream "https://$GH_TOKEN@github.com/$TRAVIS_REPO_SLUG.git"
+	git fetch upstream
+	git reset upstream/gh-pages
+
+	touch .
+	git add -A .
+	git commit -m "Rebuild docs for $REVISION"
+	git push -q upstream HEAD:gh-pages
+fi

.travis.yml

@@ -13,6 +13,7 @@ env:
     - CFLAGS="-Werror --coverage"
     - CXXFLAGS="-Werror --coverage"
     - LDFLAGS="--coverage"
+    - secure: "EysLG1MB6WCvDVpls5jsJAYsXcbHTmSFYl11UlAQCNfU+MBv7qiuOR6im3tM4ISzt4TY+OQXxEktMFRT+8govLR4UWo8dwmZ4P/2GqMbsZNPVSLkbDEy6hVv7xe5X4mp+npHthY1Z1YOLKGAh/u1PymySZz6qAzsCZ6Fq/H5Ri8="
 install:
   - if [ "$TRAVIS_OS_NAME" == "linux" ]; then pip install --user nose; fi
   - if [ "$TRAVIS_OS_NAME" == "linux" ]; then pip install --user cpp-coveralls; fi # for coveralls.io code coverage tracking
@@ -23,11 +24,14 @@ install:
 script:
   - NOCONFIGURE=1 ./autogen.sh
   - export CONFIGURE_OPTS="--with-freetype --with-glib --with-gobject --with-cairo --with-icu --with-graphite2"
+  - if [ "$TRAVIS_OS_NAME" == "linux" -a "$CC" == "gcc" ]; then export CONFIGURE_OPTS="$CONFIGURE_OPTS  --enable-gtk-doc"; fi
   - if [ "$TRAVIS_OS_NAME" == "osx" ]; then export CONFIGURE_OPTS="$CONFIGURE_OPTS --with-coretext"; fi
   - ./configure $CONFIGURE_OPTS
   - make
   - make check
   - if [ "$TRAVIS_OS_NAME" == "linux" -a "$CC" == "gcc" ]; then rm -f src/.libs/NONE.gcov; touch src/NONE; coveralls; fi
+after_success:
+  - bash .ci/deploy-docs.sh
 notifications:
   irc: "irc.freenode.org#harfbuzz"
   email: harfbuzz@lists.freedesktop.org

docs/Makefile.am

@@ -65,17 +65,19 @@ EXTRA_HFILES=$(top_builddir)/src/hb-version.h
 
 # Images to copy into HTML directory.
 # e.g. HTML_IMAGES=$(top_srcdir)/gtk/stock-icons/stock_about_24.png
-HTML_IMAGES=
+HTML_IMAGES=  \
+	HarfBuzz.png
 
 # Extra SGML files that are included by $(DOC_MAIN_SGML_FILE).
 # e.g. content_files=running.sgml building.sgml changes-2.0.sgml
 content_files=	\
-	usermanual-ch01.xml \
+	usermanual-buffers-language-script-and-direction.xml \
-	usermanual-ch02.xml \
+	usermanual-fonts-and-faces.xml \
-	usermanual-ch03.xml \
+	usermanual-glyph-information.xml \
-	usermanual-ch04.xml \
+	usermanual-hello-harfbuzz.xml \
-	usermanual-ch05.xml \
+	usermanual-install-harfbuzz.xml \
-	usermanual-ch06.xml \
+	usermanual-opentype-features.xml \
+	usermanual-what-is-harfbuzz.xml \
 	version.xml
 
 # SGML files where gtk-doc abbrevations (#GtkWidget) are expanded

docs/harfbuzz-docs.xml

@@ -7,24 +7,56 @@
 <book id="index">
   <bookinfo>
     <title>HarfBuzz Manual</title>
-    <releaseinfo>
+    <abstract>
-      for HarfBuzz &version;.
+      <title>HarfBuzz</title>
-      <!--The latest version of this documentation can be found on-line at
+      <graphic fileref="HarfBuzz.png" format="PNG" align="center"/>
-      <ulink role="online-location" url="http://[SERVER]/libharfbuzz/index.html">http://[SERVER]/libharfbuzz/</ulink>.-->
+      <para>
-    </releaseinfo>
+        HarfBuzz is an <ulink url="http://www.microsoft.com/typography/otspec/">OpenType</ulink>
+        text shaping engine.
+      </para>
+      <para>
+        The current HarfBuzz codebase, formerly known as harfbuzz-ng, is
+        versioned 1.x.x and is stable and under active maintenance. This is
+        what is used in latest versions of Firefox, GNOME, ChromeOS, Chrome,
+        LibreOffice, XeTeX, Android, and KDE, among other places. The canonical
+        source tree is available
+        <ulink url="http://cgit.freedesktop.org/harfbuzz/">here</ulink>.
+        Also available on
+        <ulink url="https://github.com/behdad/harfbuzz">github</ulink>.
+        See <xref linkend="download" endterm="download.title"/> for release tarballs.
+      </para>
+      <para>
+        The old HarfBuzz codebase, these days known as harfbuzz-old, was
+        derived from <ulink url="http://freetype.org/">FreeType</ulink>,
+        <ulink url="http://pango.org/">Pango</ulink>, and
+        <ulink url="http://qt-project.org/">Qt</ulink> and is available
+        <ulink url="http://cgit.freedesktop.org/harfbuzz.old/">here</ulink>.
+        It is not actively developed or maintained, and is extremely buggy. All
+        users are encouraged to switch over to the new HarfBuzz as soon as
+        possible.  There are no release tarballs of old HarfBuzz whatsoever.
+      </para>
+    </abstract>
   </bookinfo>
 
   <part>
     <title>User's manual</title>
-      <xi:include href="usermanual-ch01.xml"/>
+      <xi:include href="usermanual-what-is-harfbuzz.xml"/>
-      <xi:include href="usermanual-ch02.xml"/>
+      <xi:include href="usermanual-install-harfbuzz.xml"/>
-      <xi:include href="usermanual-ch03.xml"/>
+      <xi:include href="usermanual-hello-harfbuzz.xml"/>
-      <xi:include href="usermanual-ch04.xml"/>
+      <xi:include href="usermanual-buffers-language-script-and-direction.xml"/>
-      <xi:include href="usermanual-ch05.xml"/>
+      <xi:include href="usermanual-fonts-and-faces.xml"/>
-      <xi:include href="usermanual-ch06.xml"/>
+      <xi:include href="usermanual-opentype-features.xml"/>
+      <xi:include href="usermanual-glyph-information.xml"/>
   </part>
 
   <part>
+    <partinfo>
+      <releaseinfo>
+        This document is for HarfBuzz &version;.
+        <!--The latest version of this documentation can be found on-line at
+        <ulink role="online-location" url="http://[SERVER]/libharfbuzz/index.html">http://[SERVER]/libharfbuzz/</ulink>.-->
+      </releaseinfo>
+    </partinfo>
     <title>Reference manual</title>
       <chapter>
         <title>Harfbuzz API</title>

docs/usermanual-install-harfbuzz.xml

@@ -0,0 +1,70 @@
+<chapter id="install-harfbuzz">
+  <title>Install Harfbuzz</title>
+  <section id="download">
+    <title id="download.title">Download</title>
+    <para>
+      For tarball releases of HarfBuzz, look
+      <ulink url="http://www.freedesktop.org/software/harfbuzz/release/">here</ulink>.
+      At the same place you will
+      also find Win32 binary bundles that include libharfbuzz DLL, hb-view.exe,
+      hb-shape.exe, and all dependencies.
+    </para>
+    <para>
+      The canonical source tree is available
+      <ulink url="http://cgit.freedesktop.org/harfbuzz/">here</ulink>.
+      Also available on <ulink url="https://github.com/behdad/harfbuzz">github</ulink>.
+    </para>
+    <para>
+      The API that comes with <filename class='headerfile'>hb.h</filename> will
+      not change incompatibly. Other, peripheral, headers are more likely to go
+      through minor modifications, but again, will do our best to never change
+      API in an incompatible way. We will never break the ABI.
+    </para>
+    <para>
+      If you are not sure whether Pango or HarfBuzz is right for you, read
+      <ulink url="http://mces.blogspot.in/2009/11/pango-vs-harfbuzz.html">this</ulink>.
+    </para>
+  </section>
+  <section id="building">
+    <title>Building</title>
+    <para>
+      On Linux, install the development packages for FreeType, Cairo, and GLib.
+      For example, on Ubuntu / Debian, you would do:
+      <programlisting>
+<command>sudo apt-get install</command> <package>gcc g++ libfreetype6-dev libglib2.0-dev libcairo2-dev</package>
+      </programlisting>
+      whereas on Fedora, RHEL, CentOS, and other Red Hat based systems you would do:
+      <programlisting>
+<command>sudo yum install</command> <package>gcc gcc-c++ freetype-devel glib2-devel cairo-devel</package>
+      </programlisting>
+      or using MacPorts:
+      <programlisting>
+<command>sudo port install</command> <package>freetype glib2 cairo</package>
+      </programlisting>
+    </para>
+    <para>
+      If you are using a tarball, you can now proceed to running
+      <command>configure</command> and <command>make</command> as with any
+      other standard package. That should leave you with a shared library in
+      <filename>src/</filename>, and a few utility programs including hb-view
+      and hb-shape under <filename>util/</filename>.
+    </para>
+    <para>
+      If you are bootstraping from git, you need a few more tools before you
+      can run <filename>autogen.sh</filename> for the first time. Namely,
+      pkg-config and <ulink url="http://www.complang.org/ragel/">ragel</ulink>.
+      Again, on Ubuntu / Debian:
+      <programlisting>
+<command>sudo apt-get install</command> <package>autoconf automake libtool pkg-config ragel gtk-doc-tools</package>
+      </programlisting>
+      and on Fedora, RHEL, CentOS:
+      <programlisting>
+<command>sudo yum install</command> <package>autoconf automake libtool pkgconfig ragel gtk-doc</package>
+      </programlisting>
+      or using MacPorts:
+      <programlisting>
+<command>sudo port install</command> <package>autoconf automake libtool pkgconfig ragel gtk-doc</package>
+      </programlisting>
+    </para>
+  </section>
+</chapter>