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.