ceph/src/boost/libs/geometry/doc/readme.txt

   1 ===========================================================================
   2  Copyright (c) 2007-2011 Barend Gehrels, Amsterdam, the Netherlands.
   3  Copyright (c) 2008-2011 Bruno Lalande, Paris, France.
   4  Copyright (c) 2009-2011 Mateusz Loskot, London, UK
   5
   6  Use, modification and distribution is subject to the Boost Software License,
   7  Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at
   8  http://www.boost.org/LICENSE_1_0.txt)
   9 ============================================================================
  10
  11 Procedure to create documentation using Doxygen, QuickBook and doxygen_xml2qbk
  12
  13 Note that doxygen_xml2qbk is a tool currently (slightly) specific to Boost.Geometry,
  14 and that it translates from Doxygen-XML output to Quickbook (without xslt)
  15
  16 1) install Doxygen
  17 2) install QuickBook using http://www.boost.org/doc/libs/1_45_0/doc/html/quickbook/install.html#quickbook.install.linux
  18 3) unpack RapidXML, see src/docutils/tools/doxygen_xml2qbk/contrib/readme.txt
  19 4) compile doxygen_xml2qbk, in src/docutils/tools/doxygen_xml2qbk
  20 5) put binary somewhere, e.g. in /usr/local/bin/doxygen_xml2qbk
  21 6) execute python file "make_qbk.py" (calling doxygen, doxygen_xml2qbk, bjam)
  22
  23 Folders in this folder:
  24 concept: manually written documentation QBK files, on concept
  25 doxy: folders and files needed for doxygen input and output
  26 html: contains generated HTML files
  27 other: older documentation (subject to update or deletion)
  28 ref: manually written documentation QBK files, included from .hpp files
  29 reference: generated documentation QBK files (by doxygen_xml2qbk)
  30         [note: this book cannot be called "generated" or something like that,
  31         because it is used in the final URL and we want to have "reference" in it]
  32 src: examples used in documentation and tools (doxygen_xml2qbk)
  33
  34 Per new algorithm (e.g. foo), one should add:
  35 1) in file boost/geometry/algorithms/foo.hpp, include a "\ingroup foo" in the doxygen comments
  36 2) in file doc/doxy/doxygen_input/groups/groups.hpp, define the group "foo"
  37 3) in file doc/make_qbk.py, include the algorithm "foo"
  38 4) in file doc/reference.qbk, include the foo.qbk ([include generated/foo.qbk])
  39 5) in file doc/quickref.xml, include a section on foo conform other sections
  40 6) in file doc/src/docutils/tools/support_status/support_status.cpp include the algorithm (3 places) (optionally)
  41 7) in file doc/reference/foo.qbk (to be created), include the support status and write other text, and include examples (optionally)
  42 8) in file doc/imports.qbk, include the example foo.cpp (if any)
  43 9) create file doc/src/examples/algorithm/foo.cpp (optional)
  44
  45