boostorg/beast
1
0
Fork 1
mirror of https://github.com/boostorg/beast.git synced 2025-06-25 03:51:36 +02:00
Code Issues Packages Projects Releases Wiki Activity

Normalize doc build scripts

Browse Source
This commit is contained in:
Vinnie Falco
2017-07-24 13:24:15 -07:00
parent f642eebf00
commit 03ec8d4d4b
9 changed files with 145 additions and 59 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
CHANGELOG.md
View File

@ -11,6 +11,7 @@ Version 86:
* Update copyrights
* Remove spurious declaration
* Tidy up Jamfile
* Normalize doc build scripts
--------------------------------------------------------------------------------

2
doc/.gitignore vendored
View File

@ -1,4 +1,4 @@
html
temp
reference.qbk
out.txt
qbk/reference.qbk

126
doc/Jamfile
View File

@ -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 "/<!-- CONFIG_TEMPLATE -->/{r $(2[2])" -e "d}" $(1)
sed -i -e "/<!-- CLASS_DETAIL_TEMPLATE -->/{r $(2[3])" -e "d}" $(1)
sed -i -e "/<!-- INCLUDES_TEMPLATE -->/{r $(2[4])" -e "d}" $(1)
sed -i -e "/<!-- INCLUDES_FOOT_TEMPLATE -->/{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
:
<dependency>$(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
:
<dependency>qbk
;
explicit beast_doc ;
install beast_doc_images
install images
:
images/message.png
:
<location>html/beast/images
;
explicit beast_doc_images ;
explicit images ;
#-------------------------------------------------------------------------------
#
# HTML documentation for $(BOOST_ROOT)/doc/html
#
#-------------------------------------------------------------------------------
boostbook beast
:
@ -48,10 +150,16 @@ boostbook beast
<xsl:param>generate.toc="chapter toc,title section nop reference nop"
<include>../../../tools/boostbook/dtd
:
<dependency>beast_doc_images
<dependency>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 ;

16
doc/makeqbk.sh
View File

@ -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 '/<!-- CLASS_DETAIL_TEMPLATE -->/{r ../xsl/class_detail.xsl' -e 'd}' doxygen.xsl
sed -i -e '/<!-- INCLUDES_TEMPLATE -->/{r ../xsl/includes.xsl' -e 'd}' doxygen.xsl
sed -i -e '/<!-- INCLUDES_FOOT_TEMPLATE -->/{r ../xsl/includes_foot.xsl' -e 'd}' doxygen.xsl
xsltproc ../xsl/reference.xsl all.xml > ../reference.qbk

18
doc/qbk/00_main.qbk
View File

@ -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[] '''&mdash; ''']
[template indexterm1[term1] '''<indexterm><primary>'''[term1]'''</primary></indexterm>''']
[template indexterm2[term1 term2] '''<indexterm><primary>'''[term1]'''</primary><secondary>'''[term2]'''</secondary></indexterm>''']
[template repo_file[path] '''<ulink url="https://github.com/boostorg/Beast/blob/master/'''[path]'''">'''[path]'''</ulink>''']
[template include_file[path][^<'''<ulink url="https://github.com/boostorg/Beast/blob/master/include/'''[path]'''">'''[path]'''</ulink>'''>]]
[template repo_file[path] '''<ulink url="https://github.com/boostorg/beast/blob/master/'''[path]'''">'''[path]'''</ulink>''']
[template include_file[path][^<'''<ulink url="https://github.com/boostorg/beast/blob/master/include/'''[path]'''">'''[path]'''</ulink>'''>]]
[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'''<reference id="beast_hidden"><title>This Page Intentionally Left Blank 1/2</title>''']
[section:ref This Page Intentionally Left Blank 2/2]
[include ../reference.qbk]
[include reference.qbk]
[endsect]
[block'''</reference>''']

6
doc/qbk/01_intro.qbk
View File

@ -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]

16
doc/source.dox
View File

@ -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
#---------------------------------------------------------------------------

6
doc/xsl/config.xsl Normal file
View File

@ -0,0 +1,6 @@
<!-- Variables (Edit for your project) -->
<xsl:variable name="doc-ref" select="'beast.ref.'"/>
<xsl:variable name="doc-ns" select="'boost::beast'"/>
<xsl:variable name="debug" select="0"/>
<xsl:variable name="private" select="0"/>
<!-- End Variables -->

13
doc/xsl/reference.xsl
View File

@ -1,13 +0,0 @@
<?xml version="1.0" encoding="utf-8"?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
<!-- Variables (Edit for your project) -->
<xsl:variable name="doc-ref" select="'beast.ref.'"/>
<xsl:variable name="doc-ns" select="'boost::beast'"/>
<xsl:variable name="debug" select="0"/>
<xsl:variable name="private" select="0"/>
<!-- End Variables -->
<xsl:include href="../temp/doxygen.xsl"/>
</xsl:stylesheet>