[Boost-commit] svn:boost r85596 - in trunk/tools/quickbook: doc/boost-doc-tools examples/standalone-quickbook

Subject: [Boost-commit] svn:boost r85596 - in trunk/tools/quickbook: doc/boost-doc-tools examples/standalone-quickbook
From: dnljms_at_[hidden]
Date: 2013-09-08 03:45:47

Author: danieljames
Date: 2013-09-08 03:45:47 EDT (Sun, 08 Sep 2013)
New Revision: 85596
URL: http://svn.boost.org/trac/boost/changeset/85596

Log:
Example of building documentation outside of the boost tree.

Added:
   trunk/tools/quickbook/examples/standalone-quickbook/
   trunk/tools/quickbook/examples/standalone-quickbook/Jamfile.v2   (contents, props changed)
   trunk/tools/quickbook/examples/standalone-quickbook/Jamroot.jam   (contents, props changed)
   trunk/tools/quickbook/examples/standalone-quickbook/simple.qbk   (contents, props changed)
Text files modified: 
   trunk/tools/quickbook/doc/boost-doc-tools/boost-build.qbk       |    51 ++++++++++++++++++++++++++++++++++++++++
   trunk/tools/quickbook/examples/standalone-quickbook/Jamfile.v2  |    16 ++++++++++++                            
   trunk/tools/quickbook/examples/standalone-quickbook/Jamroot.jam |    45 +++++++++++++++++++++++++++++++++++     
   trunk/tools/quickbook/examples/standalone-quickbook/simple.qbk  |     5 +++                                     
   4 files changed, 117 insertions(+), 0 deletions(-)

Modified: trunk/tools/quickbook/doc/boost-doc-tools/boost-build.qbk
==============================================================================
--- trunk/tools/quickbook/doc/boost-doc-tools/boost-build.qbk	Sat Sep  7 14:16:22 2013	(r85595)
+++ trunk/tools/quickbook/doc/boost-doc-tools/boost-build.qbk	2013-09-08 03:45:47 EDT (Sun, 08 Sep 2013)	(r85596)
@@ -88,3 +88,54 @@
 xml generated from the quickbook file.
 
 [endsect] [/simple]
+
+[section:standalone Building documentation outside of the Boost tree]
+
+So far, the documentation has been built inside the boost tree, so it uses
+the boost css files and images directly from their original location.
+But when building in a separate repository the css and images files need to
+be copied into place. You can see an example of this at
+[@boost://tools/quickbook/examples/standalone-quickbook/
+ `tools/quickbook/examples/standalone-quickbook/`]. This is in the boost
+tree, but it has a `Jamroot.jam` file which makes Boost.Build treat it as
+its own build tree. Here the Jamfile is:
+
+    using boostbook ;
+    using quickbook ;
+
+    xml simple-boostbook : simple.qbk ;
+
+    boostbook simple : simple-boostbook :
+        <dependency>css
+        <dependency>images
+        ;
+
+    install css : [ glob $(BOOST_ROOT)/doc/src/*.css ]
+        : <location>html ;
+    install images : [ glob $(BOOST_ROOT)/doc/src/images/*.png ]
+        : <location>html/images ;
+    explicit css ;
+    explicit images ;
+
+This time the boostbook build target is a little different:
+
+    boostbook simple : simple-boostbook :
+        <dependency>css
+        <dependency>images
+        ;
+
+There's no reason to specify `boost.root` as the css and image files are
+copied into the documentation directory, but it does need to depend on the
+`css` and `images` targets which do the copying:
+
+    install css : [ glob $(BOOST_ROOT)/doc/src/*.css ]
+        : <location>html ;
+    install images : [ glob $(BOOST_ROOT)/doc/src/images/*.png ]
+        : <location>html/images ;
+    explicit css ;
+    explicit images ;
+
+The `BOOST_ROOT` variable needs is set in the `Jamroot.jam` file. `css` and
+`images` are marked `explicit`, so that they're only copied when required.
+
+[endsect] [/standalone]

Added: trunk/tools/quickbook/examples/standalone-quickbook/Jamfile.v2
==============================================================================
--- /dev/null	00:00:00 1970	(empty, because file is newly added)
+++ trunk/tools/quickbook/examples/standalone-quickbook/Jamfile.v2	2013-09-08 03:45:47 EDT (Sun, 08 Sep 2013)	(r85596)
@@ -0,0 +1,16 @@
+using boostbook ;
+using quickbook ;
+
+xml simple-boostbook : simple.qbk ;
+
+boostbook simple : simple-boostbook :
+    <dependency>css
+    <dependency>images
+    ;
+
+install css : [ glob $(BOOST_ROOT)/doc/src/*.css ]
+    : <location>html ;
+install images : [ glob $(BOOST_ROOT)/doc/src/images/*.png ]
+    : <location>html/images ;
+explicit css ;
+explicit images ;

Added: trunk/tools/quickbook/examples/standalone-quickbook/Jamroot.jam
==============================================================================
--- /dev/null	00:00:00 1970	(empty, because file is newly added)
+++ trunk/tools/quickbook/examples/standalone-quickbook/Jamroot.jam	2013-09-08 03:45:47 EDT (Sun, 08 Sep 2013)	(r85596)
@@ -0,0 +1,45 @@
+#
+#   Copyright (c) 2006 João Abecasis
+#
+#   Distributed under the Boost Software License, Version 1.0. (See
+#   accompanying file LICENSE_1_0.txt or copy at
+#   http://www.boost.org/LICENSE_1_0.txt)
+#
+
+##
+##  IMPORTANT NOTE: This file MUST NOT be copied over a boost installation
+##
+
+path-constant top : . ;
+
+import modules ;
+import path ;
+
+local boost-root = [ modules.peek : BOOST_ROOT ] ;
+
+if ! $(boost-root)
+{
+    local boost-search-dirs = [ modules.peek : BOOST_BUILD_PATH ] ;
+
+    for local dir in $(boost-search-dirs)
+    {
+        if [ path.glob $(dir)/../../../ : boost/version.hpp ]
+        {
+            boost-root += $(dir)/../../../ ;
+        }
+    }
+
+    if $(boost-root)
+    {
+        boost-root = [ path.make $(boost-root[1]) ] ;
+    }
+    else
+    {
+        ECHO "Warning: couldn't find BOOST_ROOT in" $(boost-root) ;
+    }
+}
+
+path-constant BOOST_ROOT : $(boost-root) ;
+modules.poke : QUICKBOOK_ROOT : $(top) ;
+
+use-project /boost : $(BOOST_ROOT) ;

Added: trunk/tools/quickbook/examples/standalone-quickbook/simple.qbk
==============================================================================
--- /dev/null	00:00:00 1970	(empty, because file is newly added)
+++ trunk/tools/quickbook/examples/standalone-quickbook/simple.qbk	2013-09-08 03:45:47 EDT (Sun, 08 Sep 2013)	(r85596)
@@ -0,0 +1,5 @@
+[article Simple Example
+    [quickbook 1.6]
+]
+
+Interesting stuff goes here.