From 03ec8d4d4b805641e40958852d2a6020dbaebc12 Mon Sep 17 00:00:00 2001 From: Vinnie Falco Date: Mon, 24 Jul 2017 13:24:15 -0700 Subject: [PATCH] Normalize doc build scripts --- CHANGELOG.md | 1 + doc/.gitignore | 2 +- doc/Jamfile | 126 +++++++++++++++++++++++++++++++++++++++--- doc/makeqbk.sh | 16 ------ doc/qbk/00_main.qbk | 18 +++--- doc/qbk/01_intro.qbk | 6 +- doc/source.dox | 16 +++--- doc/xsl/config.xsl | 6 ++ doc/xsl/reference.xsl | 13 ----- 9 files changed, 145 insertions(+), 59 deletions(-) delete mode 100755 doc/makeqbk.sh create mode 100644 doc/xsl/config.xsl delete mode 100644 doc/xsl/reference.xsl diff --git a/CHANGELOG.md b/CHANGELOG.md index a51b7c9d..e3034b43 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -11,6 +11,7 @@ Version 86: * Update copyrights * Remove spurious declaration * Tidy up Jamfile +* Normalize doc build scripts -------------------------------------------------------------------------------- diff --git a/doc/.gitignore b/doc/.gitignore index b775bdcf..4aca2ca6 100644 --- a/doc/.gitignore +++ b/doc/.gitignore @@ -1,4 +1,4 @@ html temp -reference.qbk out.txt +qbk/reference.qbk diff --git a/doc/Jamfile b/doc/Jamfile index b756d4ac..341c6971 100644 --- a/doc/Jamfile +++ b/doc/Jamfile @@ -7,31 +7,133 @@ project beast/doc ; -import boostbook : boostbook ; - -using boostbook ; -using quickbook ; -using doxygen ; +import os ; +import path ; +import boostbook ; +import quickbook ; +#------------------------------------------------------------------------------- # -# HTML documentation for $(BOOST_ROOT)/doc/html +# Build the list of header files that Doxygen will scan. We need +# this list to inform the build system of the dependencies so the +# docs can be rebuild if any of the header files change. # +local sources = [ path.glob-tree ../include/boost/beast : *.hpp *.ipp : detail impl ] ; + +#------------------------------------------------------------------------------- +# +# Generate transform.xsl. This xsl transfomration takes as input +# the Doxygen-generated XML and produces QuickBook output. +# +make transform.xsl + : + docca/include/docca/doxygen.xsl + xsl/config.xsl + xsl/class_detail.xsl + xsl/includes.xsl + xsl/includes_foot.xsl + : + @make_transform + ; + +# Make a copy of the docca transform. Then, insert our +# customizations into the speciall marked locations using sed. +# +actions make_transform +{ + cp $(2[1]) $(1) + sed -i -e "//{r $(2[2])" -e "d}" $(1) + sed -i -e "//{r $(2[3])" -e "d}" $(1) + sed -i -e "//{r $(2[4])" -e "d}" $(1) + sed -i -e "//{r $(2[5])" -e "d}" $(1) +} + +#------------------------------------------------------------------------------- +# +# Invoke Doxygen to process the header files and produce the XML +# containing the description of the C++ declarations and extracted +# Javadoc comments. +# +make reference.xml + : + ./source.dox + : + @make_xml + : + $(sources) + ; + +# Windows is a little different from other platforms +if [ os.name ] = NT +{ + actions make_xml + { + SET LIB_DIR=$(2:B=:S=..) + SET XML_OUTPUT=$(1:D) + doxygen $(2) && xsltproc $(1:B=combine:S=.xslt) $(1:B=index:S=.xml) > $(1) + } +} +else +{ + actions make_xml + { + export LIB_DIR=$(2:B=:S=..) + export XML_OUTPUT=$(1:D) + doxygen $(2) && xsltproc $(1:B=combine:S=.xslt) $(1:B=index:S=.xml) > $(1) + } +} + +#------------------------------------------------------------------------------- +# +# Produce the reference.qbk file by running +# the reference xml through the transform. +# +make reference.qbk + : + transform.xsl + reference.xml + : + @make_reference + ; + +actions make_reference +{ + xsltproc $(2) > $(1) +} + +# We have to make a copy of reference.qbk and put it +# in a place where the static .qbk files can find it +# +install qbk : reference.qbk ; + +#------------------------------------------------------------------------------- +# +# Produce the Boost.Book XML from the QuickBook +# xml beast_doc : qbk/00_main.qbk + : + qbk ; explicit beast_doc ; -install beast_doc_images +install images : images/message.png : html/beast/images ; -explicit beast_doc_images ; +explicit images ; + +#------------------------------------------------------------------------------- +# +# HTML documentation for $(BOOST_ROOT)/doc/html +# +#------------------------------------------------------------------------------- boostbook beast : @@ -48,10 +150,16 @@ boostbook beast generate.toc="chapter toc,title section nop reference nop" ../../../tools/boostbook/dtd : - beast_doc_images + images ; +#------------------------------------------------------------------------------- +# +# These are used to inform the build system of the +# means to build the integrated and stand-alone docs. +# + alias boostdoc : beast : : : ; explicit boostdoc ; diff --git a/doc/makeqbk.sh b/doc/makeqbk.sh deleted file mode 100755 index b742a28b..00000000 --- a/doc/makeqbk.sh +++ /dev/null @@ -1,16 +0,0 @@ -#!/bin/sh - -# Copyright (c) 2013-2017 Vinnie Falco (vinnie dot falco at gmail dot com) -# -# 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) - -mkdir -p temp -doxygen source.dox -cd temp -xsltproc combine.xslt index.xml > all.xml -cp ../docca/include/docca/doxygen.xsl doxygen.xsl -sed -i -e '//{r ../xsl/class_detail.xsl' -e 'd}' doxygen.xsl -sed -i -e '//{r ../xsl/includes.xsl' -e 'd}' doxygen.xsl -sed -i -e '//{r ../xsl/includes_foot.xsl' -e 'd}' doxygen.xsl -xsltproc ../xsl/reference.xsl all.xml > ../reference.qbk diff --git a/doc/qbk/00_main.qbk b/doc/qbk/00_main.qbk index 54220a3d..e020b500 100644 --- a/doc/qbk/00_main.qbk +++ b/doc/qbk/00_main.qbk @@ -7,7 +7,7 @@ [library Beast [quickbook 1.6] - [copyright 2013 - 2017 Vinnie Falco] + [copyright 2016 - 2017 Vinnie Falco] [purpose Networking Protocol Library] [license Distributed under the Boost Software License, Version 1.0. @@ -22,15 +22,15 @@ [template mdash[] '''— '''] [template indexterm1[term1] ''''''[term1]''''''] [template indexterm2[term1 term2] ''''''[term1]''''''[term2]''''''] -[template repo_file[path] ''''''[path]''''''] -[template include_file[path][^<''''''[path]''''''>]] +[template repo_file[path] ''''''[path]''''''] +[template include_file[path][^<''''''[path]''''''>]] -[def __N3747__ [@http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2013/n3747.pdf [*N3747]]] -[def __N4588__ [@http://cplusplus.github.io/networking-ts/draft.pdf [*N4588]]] -[def __rfc6455__ [@https://tools.ietf.org/html/rfc6455 rfc6455]] -[def __rfc7230__ [@https://tools.ietf.org/html/rfc7230 rfc7230]] +[def __N3747__ [@http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2013/n3747.pdf [*N3747]]] +[def __N4588__ [@http://cplusplus.github.io/networking-ts/draft.pdf [*N4588]]] +[def __rfc6455__ [@https://tools.ietf.org/html/rfc6455 rfc6455]] +[def __rfc7230__ [@https://tools.ietf.org/html/rfc7230 rfc7230]] -[def __Asio__ [@http://www.boost.org/doc/html/boost_asio.html Boost.Asio]] +[def __Asio__ [@http://www.boost.org/doc/html/boost_asio.html Boost.Asio]] [def __asio_handler_invoke__ [@http://www.boost.org/doc/html/boost_asio/reference/asio_handler_invoke.html `asio_handler_invoke`]] [def __asio_handler_allocate__ [@http://www.boost.org/doc/html/boost_asio/reference/asio_handler_allocate.html `asio_handler_allocate`]] @@ -106,7 +106,7 @@ [block'''This Page Intentionally Left Blank 1/2'''] [section:ref This Page Intentionally Left Blank 2/2] -[include ../reference.qbk] +[include reference.qbk] [endsect] [block''''''] diff --git a/doc/qbk/01_intro.qbk b/doc/qbk/01_intro.qbk index e667f9b5..56de7f6a 100644 --- a/doc/qbk/01_intro.qbk +++ b/doc/qbk/01_intro.qbk @@ -56,10 +56,10 @@ Beast requires: Supported compilers: msvc-14+, gcc 4.8+, clang 3.6+ -Sources are [*header-only]. To link a program using Beast successfully, add the +Sources are [*header-only]. +To link a program using Beast successfully, add the [@http://www.boost.org/libs/system/doc/reference.html Boost.System] -library to the list of linked libraries. If you use coroutines -you'll also need the +library to your build scripts. If you use coroutines you'll also need the [@http://www.boost.org/libs/coroutine/doc/html/index.html Boost.Coroutine] library. Please visit the [@http://www.boost.org/doc/ Boost documentation] diff --git a/doc/source.dox b/doc/source.dox index af02a48c..3a5d24b6 100644 --- a/doc/source.dox +++ b/doc/source.dox @@ -4,8 +4,8 @@ DOXYFILE_ENCODING = UTF-8 PROJECT_NAME = "Beast" PROJECT_NUMBER = -PROJECT_BRIEF = C++ Library -PROJECT_LOGO = images/beast.png +PROJECT_BRIEF = C++ Networking Library +PROJECT_LOGO = OUTPUT_DIRECTORY = CREATE_SUBDIRS = NO ALLOW_UNICODE_NAMES = NO @@ -103,11 +103,11 @@ WARN_LOGFILE = # Configuration options related to the input files #--------------------------------------------------------------------------- INPUT = \ - ../include/boost/beast/ \ - ../include/boost/beast/core \ - ../include/boost/beast/http \ - ../include/boost/beast/websocket \ - ../include/boost/beast/zlib + $(LIB_DIR)/include/boost/beast/ \ + $(LIB_DIR)/include/boost/beast/core \ + $(LIB_DIR)/include/boost/beast/http \ + $(LIB_DIR)/include/boost/beast/websocket \ + $(LIB_DIR)/include/boost/beast/zlib INPUT_ENCODING = UTF-8 FILE_PATTERNS = @@ -253,7 +253,7 @@ MAN_LINKS = NO # Configuration options related to the XML output #--------------------------------------------------------------------------- GENERATE_XML = YES -XML_OUTPUT = temp/ +XML_OUTPUT = $(XML_OUTPUT) XML_PROGRAMLISTING = YES #--------------------------------------------------------------------------- diff --git a/doc/xsl/config.xsl b/doc/xsl/config.xsl new file mode 100644 index 00000000..798a532c --- /dev/null +++ b/doc/xsl/config.xsl @@ -0,0 +1,6 @@ + + + + + + diff --git a/doc/xsl/reference.xsl b/doc/xsl/reference.xsl deleted file mode 100644 index 5cf6af2c..00000000 --- a/doc/xsl/reference.xsl +++ /dev/null @@ -1,13 +0,0 @@ - - - - - - - - - - - - -