[Boost-commit] svn:boost r72627 - sandbox/SOC/2011/checks/libs/checks/doc

Subject: [Boost-commit] svn:boost r72627 - sandbox/SOC/2011/checks/libs/checks/doc
From: pbristow_at_[hidden]
Date: 2011-06-17 07:57:21

Author: pbristow
Date: 2011-06-17 07:57:20 EDT (Fri, 17 Jun 2011)
New Revision: 72627
URL: http://svn.boost.org/trac/boost/changeset/72627

Log:
jamfile.v2 but renamed as just jamfile to avoid clash with Jamfile.v2  (note caps) that must be deleted somehow.
Added:
   sandbox/SOC/2011/checks/libs/checks/doc/jamfile   (contents, props changed)

Added: sandbox/SOC/2011/checks/libs/checks/doc/jamfile
==============================================================================
--- (empty file)
+++ sandbox/SOC/2011/checks/libs/checks/doc/jamfile	2011-06-17 07:57:20 EDT (Fri, 17 Jun 2011)
@@ -0,0 +1,342 @@
+# \boost-sandbox\SOC\2011\checks\doc jamfile.v2
+
+# Creating Boost documentation for Checks.
+
+# Copyright Pierre Talbot 2011
+
+# 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)
+
+# Reminder: whitespace MUST terminate variable name!
+# so spaces or newlines BEFORE ; and : and AFTER too.
+# (because : and ; are keywords!)
+
+project checks ; # Insert your project name here.
+
+using quickbook ;  # Required if you want to use Quickbook.
+using doxygen ;  # Required if you want to use Doxygen.
+#using auto-index ; # Required if you want to use autoindexing.
+
+import modules ;
+import path ;
+import os ; # Needed to get environment variables.
+
+# Set up Boost root folder.
+# For example, might be current release, a previous release, or trunk.
+#  Assumes you have set an environment variable $BOOST_ROOT.
+local BOOST_ROOT = [ os.environ BOOST_ROOT ] ;
+ECHO "os.environ BOOST_ROOT boost-root = " $(BOOST_ROOT) ; #  Upper case for the value of environment variable(s).
+# For example: os.environ BOOST_ROOT boost-root =  /boost_1_47_0
+
+ECHO "BOOST_ROOT " $(BOOST_ROOT) ;
+path-constant local-boost-root : $(BOOST_ROOT) ; # Or you can access your chosen boost version here.
+ECHO "local-boost-root = " $(local-boost-root) ; # local-boost-root =  I:\boost_1_47_0
+
+local boost_sandbox = [ os.environ BOOST_SANDBOX ] ;
+ECHO "os.environ boost-sandbox = " $(boost_sandbox) ; #  Upper case for the value of environment variable(s).
+
+path-constant here : . ; # Convenient to refer to files in the same directory as this jamfile.v2.
+ECHO "here = " $(here) ; 
+
+path-constant nav_images : html/images/ ; # png and svg images for home, next, note, tip...
+# path-constant images_location : ../doc/html/images ; # location of Checks images referenced by Quickbook.
+#  MIght like some fancy pictures of credit cards etc...
+path-constant images_location : html/images ; # location of SVG and PNG images referenced by Quickbook.
+
+echo "images_location" $(images_location) ; 
+echo "nav_images" $(nav_images) ;
+
+if --enable-index in  [ modules.peek : ARGV ]
+{
+   ECHO "Building the Checks docs with automatic index generation enabled." ;
+   using auto-index ;
+   project : requirements
+        <auto-index>on # Turns on index (or off).
+        
+        <auto-index-verbose>on
+        
+        # Choose indexing method (separately for html and pdf):
+        <format>html:<auto-index-internal>on  # on (or off) to use internally generated indexes.
+        # <format>html:<xsl:param>generate.index=0 # Don't let the XSL stylesheets generate indexes.
+        
+        <format>pdf:<auto-index-internal>off # on (or off) to use internally generated indexes.
+        # <auto-index-type>index  # Use <index>...</index> as the XML wrapper.
+        
+        <format>pdf:<xsl:param>index.on.type=1 # For the native stylesheets to generate the different indexes.
+        # PDF native index support is probably better for PDFs as then you actually get page numbers.
+
+        <auto-index-script>checks.idx # Specifies the name of the index script to load. 
+        # <auto-index-prefix>../../../ # OK for Boost /boost and /libs normal directory layout 
+        # using scan-path in checks.idx, for example:
+        
+        # Assume all header files are in boost/checks and sub-folders.
+				#!scan-path boost/checks ".*\.hpp" true
+				
+				# Assume all Quickbook files are in /docs (none in sub-folders).
+				#!scan-path "libs/checks" ".*\.qbk"
+
+        <auto-index-prefix>../../.. 
+        
+        # Inform Quickbook that there is to be an index(es).
+        <quickbook-define>enable_index
+        
+        ;
+}
+else
+{
+   ECHO "Building the Checks docs with automatic index generation disabled. To get an auto-index, try building with --enable-index." ;
+}
+
+doxygen autodoc
+  :
+    [ glob ../../../boost/checks/*.hpp ] # These are your hpp header include files.
+    [ glob ../../../boost/checks/*.cpp ] # These are your cpp source files.
+  : 
+    # Lots of parameters passed to Doxygen.  You can see these in the doxygen docs, or the Wizard Expert tab displays them.
+    # If you have successfuly built your Doxygen docs standalone using the Wizard (strongly recommended as it is much quicker).
+    # The values in your project's doxyfile are what to put as the Doxygen parameters passed below.
+    <doxygen:param>WARNINGS=YES # Default NO, but useful to see warnings, especially in a logfile.
+    # It is also wise to to set a warnings logfile like this:
+    <doxygen:param>WARN_LOGFILE=AutoDoxywarnings.log # This may not be empty (usually not a good sign!), depending on options chosen.
+    # Much better to send message to a logfile than the default stderr.
+    # and make sure that there are no Doxygen errors or significant warnings in the log file.
+
+    <doxygen:param>WARN_IF_UNDOCUMENTED=NO # Default NO but useful if you aim to Doxygen document *all* members.
+    <doxygen:param>WARNINGS=YES # Default NO, but useful to see warnings, especially in a logfile.
+    <doxygen:param>QUIET=NO # Default NO, and best left as NO.
+    <doxygen:param>WARN_NO_PARAMDOC=NO # Default no, but YES useful if you aim to document all function parameters.
+    # <doxygen:param>DOXYFILE_ENCODING=UTF-8 # Default is UTF-8 which is almost certainly OK.
+    <doxygen:param>PROJECT_NAME="Quickbook Doxygen Indexing Documentation Prototype" # Shows on Doxygen main page (if you have one).
+    <doxygen:param>PROJECT_NUMBER=1 # Might be useful for version numbering?
+    <doxygen:param>TAB_SIZE=2 # or your choice.
+    # <doxygen:param>OUTPUT_DIRECTORY # Default is current directory.
+    # <doxygen:param>CREATE_SUBDIRS=YES # Unlike to be useful except for a very large project.
+    # <doxygen:param>BRIEF_MEMBER_DESC=YES # Doxygen will include brief member descriptions by default, and is what you want.
+    # <doxygen:param>REPEAT_BRIEF=YES # Prepend brief description before detailed, default and is what you want.
+    # <doxygen:param>ALWAYS_DETAILED_SEC=NO # Probably not wanted.
+    # <doxygen:param>ABBREVIATE_BRIEF=NO # Probably not wanted.
+    # <doxygen:param>EXTRACT_ALL=YES # Documents everything, probably best to use to start and only extract selected items if it proves to be unmanageable.
+    <doxygen:param>INLINE_INHERITED_MEMB=YES # Show all inherited members of a class in the documentation of that class as if those members were ordinary class members.
+    <doxygen:param>SORT_MEMBER_DOCS=YES # sort docs into alphabetical order - generally useful.
+    #<doxygen:param>EXTRACT_PRIVATE=YES # Show all private members. Less useful for user documentation.
+    <doxygen:param>EXTRACT_PRIVATE=NO # If the EXTRACT_PRIVATE tag is set to YES all private members of a class will be included in the documentation
+    <doxygen:param>EXTRACT_STATIC=YES # Show all static members.
+
+    # <doxygen:param>EXTRACT_LOCAL_METHODS=YES # Only useful for Objective C.
+    # <doxygen:param>EXTRACT_ANON_NSPACES=YES # Probably not useful for user documentation?
+    <doxygen:param>EXTRACT_LOCAL_CLASSES=YES # If the EXTRACT_LOCAL_CLASSES tag is set to YES classes (and structs) defined locally in source files will be included in the documentation.
+    <doxygen:param>EXTRACT_LOCAL_METHODS=YES # Less useful for user documentation.
+    # The following are over-ridden by EXTRACT_ALL=YES
+    <doxygen:param>HIDE_UNDOC_MEMBERS=NO # Not useful unless you have carefully documented all members that you want Doxygen to list.
+    <doxygen:param>HIDE_UNDOC_CLASSES=YES # YES if you only want the items you *have* specifically documented all members that you want Doxygen to list.
+    <doxygen:param>HIDE_UNDOC_MEMBERS=NO # NO if you want all members Doxygen documented.
+    <doxygen:param>HIDE_FRIEND_COMPOUNDS=NO # Default is NO and will append friend information.
+    #<doxygen:param>HIDE_INBODY_DOCS=NO # Default is NO and will append this information. Option no longer supported?
+    <doxygen:param>INTERNAL_DOCS=YES # Allows implemented details NOT to be included in public docs.
+    <doxygen:param>CASE_SENSE_NAMES=NO # Must be NO for Boost which may include Windows file system.  (means that all file names are lower case)
+    <doxygen:param>HIDE_SCOPE_NAMES=NO # Default NO is not to full qualify members with class and namespace.
+    <doxygen:param>SORT_MEMBER_DOCS=YES # Default YES is to sort alphabetically.
+    <doxygen:param>SORT_BRIEF_DOCS=YES # Default is to sort brief documentation alphabetically.
+    <doxygen:param>SORT_MEMBERS_CTORS_1ST=NO # Default No puts constructors and destructors first.
+    # Preprocessor settings.
+    # Some ugly examples of predefined macro calls (from Boost.Units library) :(
+    <doxygen:param>"PREDEFINED= \\
+            \"BOOST_UNITS_STATIC_CONSTANT(a,b)=static const b a\" \\
+            \"BOOST_UNITS_TYPEOF(a)=typeof(a)\" \\
+            \"BOOST_PREVENT_MACRO_SUBSTITUTION=\" \\
+            \"BOOST_UNITS_HAS_TYPEOF=1\""
+    <doxygen:param>ENABLE_PREPROCESSING=YES # Evaluates all C-preprocessor directives found in files.
+    <doxygen:param>MACRO_EXPANSION=YES # Will expand all macro names.
+    <doxygen:param>EXPAND_ONLY_PREDEF=YES # Only predefined macros expanded.  See units library for an example.
+    <doxygen:param>SEARCH_INCLUDES=YES # Search #include files found.
+    <doxygen:param>INLINE_INFO=YES # If the INLINE_INFO tag is set to YES (the default) then a tag [inline] is inserted in the documentation for inline members.
+    <doxygen:param>SORT_BRIEF_DOCS=YES # If the SORT_BRIEF_DOCS tag is set to YES then doxygen will sort the brief descriptions of file, namespace and class members alphabetically by member name.
+    <doxygen:param>SORT_MEMBER_DOCS=YES # If the SORT_MEMBER_DOCS tag is set to YES (the default) then doxygen will sort the (detailed) documentation of file and class members alphabetically by member name.
+    <doxygen:param>SHOW_INCLUDE_FILES=NO # List of the files that are included by a file in the documentation of that file.
+    <doxygen:param>REPEAT_BRIEF=YES # Prepend the brief description of a member or function before the detailed description
+    <doxygen:param>BRIEF_MEMBER_DESC=YES # Include brief member descriptions after the members that are listed in the file and class
+    <doxygen:param>MULTILINE_CPP_IS_BRIEF=YES # Treat a multi-line C++ special comment block (i.e. a block of //! or /// comments) as a brief description.
+    # May be best to always use \brief and \details to avoid ambiguity?
+    # <doxygen:param>STRIP_FROM_PATH=NO # Most useful to leave default to strip just the directory from which Doxygen is run.
+    # Yes gives the full path, but NO is more useful, only giving enough to be
+    # <doxygen:param>CPP_CLI_SUPPORT=NO # unless, most unusually, you are compiled for a 'managed' CLI application.
+    <doxygen:param>SHOW_USED_FILES=YES # Default YES to show a list files used to generate documention.
+    <doxygen:param>SHOW_DIRECTORIES=YES # Default NO, but useful to show directory heirarchy.
+    <doxygen:param>SHOW_FILES=YES # Default YES is to include a tab for a page of files listed.  Useful.
+    <doxygen:param>SHOW_NAMESPACES=YES # Default YES to include tab for list of namespaces.  Useful if you have namespacess other than boost::
+
+    <doxygen:param>FILE_PATTERNS= # Types of files to be used as input. Default includes *.c *.cc *.cxx *.cpp *.c++ *.ipp *.i++ *.inl *.h *.hh *.hxx *.hpp *.h++ *.py
+    #  Might include .qbk?
+
+    <doxygen:param>RECURSIVE=YES # Search recursively down subdirectories.
+    <doxygen:param>EXCLUDE= # Files or directories that should be excluded from INPUT source files.
+    #  Headers and footers are actually rather attractive,
+    <doxygen:param>HTML_HEADER="doxygen/checks_doxygen_header.html" # A sample including a draft stamp and 'Not_Yet_In_Boost' logo.
+    #  Take care that if you use this (recommended), you need to ensure that the html
+    <doxygen:param>HTML_FOOTER="doxygen/checks_doxygen_footer.html" # This is very useful to add copyright, date of revision, versioning etc.
+
+     # A custom stylesheet is also useful, as the default syntax coloring is 'unusual' ;-)
+    <doxygen:param>HTML_STYLESHEET="doxygen/doxygen.css" # Placed in the doxygen directory,
+    # this will change to your choice of C++ syntax coloring when viewing source from Doxygen.
+    # Users can place (or edit) their own personal choice CSS file here.
+    
+    # Default is just Reference but you can provide your own title for reference section here.
+    <xsl:param>"boost.doxygen.reftitle=Checks Reference"
+
+;
+    #<doxygen:param>"PREDEFINED=\"BOOST_DEDUCED_TYPENAME=typename\" "
+    # See Doxygen configuration for detailed explanation of these options.
+    # And if you have (wisely) produced the Doxygen index first using the Wizard,
+    # see your doxyfile (which you should save in the project's Doxygen directory).
+
+
+xml checks
+  :
+    checks.qbk # This is your 'root' Quickbook file (that may include other .qbk files).
+  :
+;
+
+boostbook standalone
+  :
+     checks
+  :
+  
+  # Path for links to Boost:
+  #<xsl:param>boost.root=\$(local-boost-root) # Link to Boost logo boost.png
+  # Links are relative and trying to make absolute does NOT work.
+  # And remember that all links MUST (unless in quotes) use  backslash, not forward that is trip char.
+
+  # Grep through our stylesheet layer in $(local-boost-root)/tools/boostbook/xsl for xsl:params you can alter.
+  #  main xsl param reference for docbook http://docbook.sourceforge.net/release/xsl/current/doc/
+
+  <xsl:param>boost.root=../../../../../../../boost_trunk # OK but link to I:/boost_trunk/boost.png
+
+  # Also control links to admonitions, so need to set separately.
+  #<xsl:param>boost.root=../../../../../../../boost_1_46_0 # OK file:///I:/boost_1_46_0/boost.png
+  # Quickbook [@boost:/boost/units/detail/utility.hpp] should make it relative to xsl parameter boost.root.
+
+  # [@boost:boost.png Boost logo]  # xsl parameter boost.root, for example I:/boost_1_45_0/boost.png
+
+  # Path for libraries index:
+  <xsl:param>boost.libraries=../../../../../../../boost_1_46_0/libs/libraries.htm
+  # Use the main Boost stylesheet:
+  #<xsl:param>html.stylesheet=$(local-boost-root)/doc/html/boostbook.css #?  better
+  <xsl:param>html.stylesheet=./boostbook.css # in /doc folder.
+
+  # Use the your own local Boost stylesheet:
+  # <xsl:param>html.stylesheet=../html/boostbook.css
+
+  # Some general style settings:
+  #   see http://docbook.sourceforge.net/release/xsl/current/doc/html/index.html
+  <xsl:param>table.footnote.number.format=1 # Identifies the format used for footnote numbers in tables.
+  <xsl:param>footnote.number.format=1 # Identifies the format used for text footnote numbers.
+
+  # Default to not including the Boost logo in the navbar, when one expressly asks to include the navbar.
+  # Boost jamroot now includes
+  # Default to not include a navbar.
+  #<xsl:param>nav.layout=none # No navigation bar (home, prev, next).
+  # defining creates a runtime error: Global parameter nav.layout already defined
+  <xsl:param>nav.layout=horizontal # to get a horizontal navigation bar (you probably DO want this).
+
+  <xsl:param>boost.image=Boost # options are: none (no logo), Boost (for boost.png), or your own logo like inspired_by_boost.png
+  <xsl:param>boost.image.src=./images/proposed_for_boost.png #
+  <xsl:param>boost.image.w=180 # Width of logo in pixels. (JM has W = 162, h = 46)
+  <xsl:param>boost.image.h=90 # Height of logo in pixels.
+
+  # HTML options:
+  # ------------
+  <xsl:param>navig.graphics=1  # Use graphics not text for navigation.
+  <xsl:param>chunk.section.depth=10  # How far down we chunk nested sections, basically all of them.
+  <xsl:param>chunk.first.sections=1  # Don't put the first section on the same page as the TOC.
+  <xsl:param>toc.section.depth=10  # How far down sections get TOCs.
+  <xsl:param>toc.max.depth=4  # Max depth in each TOC.
+  <xsl:param>generate.section.toc.level=10  # How far down we go with TOCs.
+                           
+  #<format>html:<xsl:param>img.src.path=$(images_location)/ # Path of image (.png) files. (Note trailing /) 
+  # This doesn't work??? 
+  
+  #<format>html:<xsl:param>admon.graphics.extension=".png"  # default type for admonitions (important, warning, note ...)
+  #<format>html:<xsl:param>admon.graphics.path=$(nav-images)/ # path to admonition (warning, note...) image (.png) files.
+  
+  # <xsl:param name="draft.watermark.image">http://docbook.sourceforge.net/release/images/draft.png>
+
+  # PDF Options:
+  # -----------
+  # TOC Generation
+  <xsl:param>fop1.extensions=0 # DISable extensions for FOP version 0.90 and later .
+  <format>pdf:<xsl:param>fop.extensions=0 # DISable extensions for FOP version 0.20.5 and earlier.
+  <format>pdf:<xsl:param>xep.extensions=1 # Use XEP extension- PDF bookmarks, document information and better index processing.
+
+  # No indent on body text:
+  <format>pdf:<xsl:param>body.start.indent=0pt #
+  <format>pdf:<xsl:param>paper.type=A4  # Paper type = A4
+  #  http://xml.resource.org/public/rfc/html/rfc2346.html
+  #  Making Postscript and PDF International, J Palme, RFC 2346 recommends
+  #  If you are using US letter paper format, ensure that both left and right margins are at least 21 mm (0.8 in).
+  #  If you are using A4 paper, ensure that both the top and bottom margins are at least 33 mm (1.3 in).
+  # Margins sizes:
+  #<format>pdf:<xsl:param>page.margin.top=1.3in
+  #<format>pdf:<xsl:param>page.margin.inner=0.8in
+  #<format>pdf:<xsl:param>page.margin.bottom=1.3in
+  #<format>pdf:<xsl:param>page.margin.outer=0.8in
+
+  # http://docbook.sourceforge.net/release/xsl/current/doc/index.html
+  # DocBook XSL Stylesheets: Reference Documentation.
+
+  # Yes, we want graphics for admonishments:
+  <xsl:param>admon.graphics=1
+  # Set these one for PDF generation *only*:
+  #
+  # In PDF format, default PNG graphics are awful, so better use SVG images (type .svg) instead.
+  <format>pdf:<xsl:param>admon.graphics.extension=".svg"  #
+  <format>pdf:<xsl:param>use.role.for.mediaobject=1 # Use print role on next line.
+  <format>pdf:<xsl:param>preferred.mediaobject.role=print # pdf role is to be printed.
+  <format>pdf:<xsl:param>img.src.path=$(images_location)/ # Path of image (.svg) files. (Note trailing /) ? //
+  #<format>pdf:<xsl:param>img.src.path=../ # alternative location of images.
+  <format>pdf:<xsl:param>admon.graphics.path=$(nav_images)/ # path to admonition (warning, note...) image (.svg) files.
+  <format>pdf:<xsl:param>draft.mode="yes" # Yes if draft watermark wanted!
+  #<format>pdf:<xsl:param>draft.watermark.image="draft.png" # Watermark.
+  #<format>pdf:<xsl:param>draft.watermark.image=http://docbook.sourceforge.net/release/images/draft.png # Watermark.
+	#<format>pdf:<xsl:param>boost.url.prefix=I:/boost-sandbox/tools/checks/libs/checks/doc/html
+	# is absolute reference!
+	#<format>pdf:<xsl:param>boost.url.prefix=I:/boost-sandbox/tools/checks/libs/checks/doc/html
+	
+  <dependency>autodoc # Doxygen  reference section
+  # <dependency>pdf-install # final pdf
+  <dependency>png-install # Boost standard icons in both png
+	<dependency>svg-install # and svg.
+  ;
+
+# To install a copy of 'master' boostbook.css and logo.
+# install html : ../../../doc/html/boostbook.css ;
+# install ../ : ../../../boost.png ;
+
+# Install (copy) the 'master' copy of boostbook Cascading Style sheet
+# from your current Boost-root to the /doc/html folder.
+path-constant boost-root : [ modules.peek : BOOST ] ;
+install css-install : $(boost-root)/doc/src/boostbook.css : <location>html ;
+
+path-constant boost-root : [ modules.peek : BOOST ] ;
+
+
+# Install (copy) the 'master' copies of all icon images (both PNG and SVG)
+# and the Boost logo from your current Boost-root
+# to the local /doc/html/images folder so that html is complete and standalone. 
+install png-install : [ glob $(boost-root)/doc/src/images/*.png $(boost-root)/boost.png ] : <location>html/images ;
+install svg-install : [ glob $(boost-root)/doc/src/images/*.svg ] : <location>html/images ;
+
+ #   install unordered_pdf : standalone/<format>pdf : <location>. ;
+ #   explicit unordered_pdf ;
+ # The explicit rule is there so that it's only installed when the target is explicitly named.
+
+# Effectively copies the file from \bin folder to the \doc folder.
+# install pdf-install : standalone : <location>. <install-type>PDF ;
+# But will not work as expected if doxygen and/or autoindex is used
+# because a modified pdf file is created, so this command below
+# will rename the file to the expected filename, here quick_auto_dox_index.pdf.
+# <location>. means installed in same place as this jamfile, /doc.
+
+install pdf-install : standalone : <install-type>PDF <location>. <name>checks.pdf ;
+
+install callouts : [ glob src/images/callouts/*.png ] : <location>html/images/callouts ;
\ No newline at end of file