From 9403530b598b271be004597a1d6bb7755ecf09dd Mon Sep 17 00:00:00 2001 From: Dmitry Arkhipov Date: Mon, 5 Apr 2021 08:38:41 +0300 Subject: [PATCH] Use Docca jam module --- doc/.gitignore | 1 - doc/Jamfile | 271 ++++++++----------------------------------------- doc/source.dox | 256 ---------------------------------------------- 3 files changed, 45 insertions(+), 483 deletions(-) delete mode 100644 doc/source.dox diff --git a/doc/.gitignore b/doc/.gitignore index 4aca2ca6..b3ee8572 100644 --- a/doc/.gitignore +++ b/doc/.gitignore @@ -1,4 +1,3 @@ html temp out.txt -qbk/reference.qbk diff --git a/doc/Jamfile b/doc/Jamfile index e7f58f62..699edc0b 100644 --- a/doc/Jamfile +++ b/doc/Jamfile @@ -1,5 +1,6 @@ # # Copyright (c) 2019 Vinnie Falco (vinnie.falco@gmail.com) +# Copyright (c) 2021 Dmitry Arkhipov (grisumbras@gmail.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) @@ -9,238 +10,56 @@ project json/doc ; -import os ; -import path ; import boostbook ; -import quickbook ; -import xsltproc ; -import doxygen ; -import modules ; -import saxonhe ; +import ../../../tools/docca/docca.jam ; -path-constant out : . ; -#------------------------------------------------------------------------------- -# -# 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/json : *.hpp *.ipp : detail impl ] ; - -# Get the configured paths to doxygen and xsltproc - -.doxygen = [ doxygen.name ] ; -.doxygen ?= doxygen ; - -.xsltproc = [ xsltproc.name ] ; -.xsltproc ?= xsltproc ; - -#------------------------------------------------------------------------------- -# -# Invoke Doxygen to process the header files and produce the XML -# containing the description of the C++ declarations and extracted -# Javadoc comments. -# -make index.xml +docca.reference reference.qbk : - ./source.dox + xsl/custom-overrides.xsl + [ glob-tree-ex ../include/boost/json : *.hpp *.ipp : detail impl ] : - @make_doxygen_xml - : - $(sources) + PROJECT_NAME=JSON + PROJECT_BRIEF="JSON Library" + ALIASES="esafe=\"@par Exception Safety\"" + FILE_PATTERNS= + EXAMPLE_PATTERNS= + DISTRIBUTE_GROUP_DOC=YES + MACRO_EXPANSION=YES + EXPAND_ONLY_PREDEF=YES + "PREDEFINED=\\ + BOOST_FORCEINLINE \\ + BOOST_JSON_CLASS_DECL \\ + BOOST_JSON_DECL \\ + BOOST_JSON_DOCS \\ + BOOST_JSON_PUBLIC \\ + BOOST_SYMBOL_VISIBLE \\ + \"BOOST_JSON_INLINE_VARIABLE(v, t)=constexpr t v;\" \\ + \"BOOST_JSON_NODISCARD=[[nodiscard]]\" \\ + \"BOOST_JSON_NS_BEGIN=namespace boost { namespace json {\" \\ + \"BOOST_JSON_NS_END=}}\"" + ABBREVIATE_BRIEF= + INLINE_INHERITED_MEMB=YES + JAVADOC_AUTOBRIEF=YES + AUTOLINK_SUPPORT=NO + EXTRACT_ALL=YES + EXTRACT_PRIVATE=YES + EXTRACT_LOCAL_CLASSES=NO + SHOW_INCLUDE_FILES=NO + INLINE_INFO=NO + SORT_MEMBER_DOCS=NO + SORT_MEMBERS_CTORS_1ST=YES + SHOW_USED_FILES=NO + SHOW_FILES=NO + SHOW_NAMESPACES=NO + CLASS_DIAGRAMS=NO + + # ALLOW_UNICODE_NAMES=NO + # GROUP_NESTED_COMPOUNDS=NO + # HIDE_COMPOUND_REFERENCE=NO + # WARN_AS_ERROR=NO ; -rule make_doxygen_xml ( targets * : sources * : properties * ) -{ -} - -if [ os.name ] = NT -{ - actions make_doxygen_xml - { - SET LIB_DIR=$(LIB_DIR) - SET XML_OUTPUT=$(1:D) - "$(.doxygen)" $(2) - } -} -else -{ - actions make_doxygen_xml - { - export LIB_DIR=$(LIB_DIR) - export XML_OUTPUT=$(1:D) - "$(.doxygen)" $(2) - } -} - -#------------------------------------------------------------------------------- -# -# Copy all the XSLT modules to the target directory. -# -# FIXME: Change this so we can just specify a directory, -# rather than every file individually. -# -# Also, somehow force dependencies in a general way -# such that the XSLT has to be executed again -# if any of the modules change. For example, -# if base-extract-xml-pages.xml changes, then -# an invocation of extract-xml-pages.xsl (which -# imports the former) must be run again. -# -path-constant docca : ../../../tools/docca ; -make extract-xml-pages.xsl : $(docca)/include/docca/extract-xml-pages.xsl : @copy_script ; -make base-extract-xml-pages.xsl : $(docca)/include/docca/base-extract-xml-pages.xsl : @copy_script ; -make common.xsl : $(docca)/include/docca/common.xsl : @copy_script ; -make stage1.xsl : $(docca)/include/docca/stage1.xsl : @copy_script ; -make base-stage1.xsl : $(docca)/include/docca/base-stage1.xsl : @copy_script ; -make stage2.xsl : $(docca)/include/docca/stage2.xsl : @copy_script ; -make base-stage2.xsl : $(docca)/include/docca/base-stage2.xsl : @copy_script ; -make assemble-quickbook.xsl : $(docca)/include/docca/assemble-quickbook.xsl : @copy_script ; -make emphasized-types.xsl : $(docca)/include/docca/emphasized-types.xsl : @copy_script ; -make base-config.xsl : $(docca)/include/docca/base-config.xsl : @copy_script ; - -# Copy the project-specific config XSLT -make custom-overrides.xsl : xsl/custom-overrides.xsl : @copy_script ; - -# Make a copy of the given file. -# -actions copy_script -{ - cp $(2[1]) $(1) -} - - -# This is to initially create the directory as a side effect; I'm sure there's a better way... -make xml-pages/directory/placeholder : index.xml : @null_action ; - -#------------------------------------------------------------------------------- -# -# Run index.xml through the first transformation stage -# (assembling and splitting the XML into page-specific files). -# -make xml-pages.xml - : - index.xml - extract-xml-pages.xsl - - # Make bjam aware of additional dependencies - base-extract-xml-pages.xsl - base-config.xsl - custom-overrides.xsl - common.xsl - : - saxonhe.saxonhe - ; - -# This is just to make the directory eligible as a source -make xml-pages : index.xml : @null_action ; - -# Not ready for prime time until I figure out how to get the xslt-visualizer code in place -#make stage1/code-trace-enabled/stage1.xsl -# : -# stage1.xsl -# xslt-visualizer/xsl/trace-enable.xsl -# : -# saxonhe.saxonhe -# ; - -# This is to initially create the directory as a side effect; I'm sure there's a better way... -make stage1/results/directory/placeholder : xml-pages.xml : @null_action ; -make stage2/results/directory/placeholder : xml-pages.xml : @null_action ; - -# TODO: figure out why this (and the following stage) get built every time -make stage1/results - : - xml-pages - stage1.xsl - - # additional dependencies - xml-pages.xml - base-stage1.xsl - base-config.xsl - custom-overrides.xsl - common.xsl - : - saxonhe.saxonhe_dir - ; - -make stage2/results - : - stage1/results - stage2.xsl - - # additional dependencies - emphasized-types.xsl - base-stage2.xsl - base-config.xsl - custom-overrides.xsl - common.xsl - : - saxonhe.saxonhe_dir - ; - -make reference.qbk - : - xml-pages.xml - assemble-quickbook.xsl - - # TODO: make this input to the XSLT somehow - # rather than relying on it being hard-coded - # in the XSLT (which it is!) - stage2/results - : - saxonhe.saxonhe - ; - -actions make_dir -{ - mkdir $(1) -} - -make combine.xslt : index.xml : @null_action ; - -actions touch_file -{ - touch $(1) ; -} - -actions null_action -{ - touch -c $(1) ; -} - -make reference.xml - : - combine.xslt - index.xml - : - @call-xsltproc - ; - -actions call-xsltproc -{ - "$(.xsltproc)" $(2) > $(1) -} - -#------------------------------------------------------------------------------- -# -# Produce the reference.qbk file by running -# the reference xml through the transform. -# -#make reference.qbk -# : -# reference.xml -# transform.xsl -# : -# saxonhe.saxonhe -# ; - -# 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 ; #------------------------------------------------------------------------------- # @@ -260,8 +79,8 @@ xml json_doc : qbk/main.qbk : + reference.qbk images - qbk ; explicit json_doc ; diff --git a/doc/source.dox b/doc/source.dox deleted file mode 100644 index f48bb25e..00000000 --- a/doc/source.dox +++ /dev/null @@ -1,256 +0,0 @@ -#--------------------------------------------------------------------------- -# Configuration options related to the input files -#--------------------------------------------------------------------------- - -INPUT = $(LIB_DIR)/include/boost/json/ - -ALIASES += esafe="@par Exception Safety" - -INPUT_ENCODING = UTF-8 -FILE_PATTERNS = -RECURSIVE = NO -EXCLUDE = -EXCLUDE_SYMLINKS = NO -EXCLUDE_PATTERNS = -EXCLUDE_SYMBOLS = -EXAMPLE_PATH = -EXAMPLE_PATTERNS = -EXAMPLE_RECURSIVE = NO -IMAGE_PATH = -INPUT_FILTER = -FILTER_PATTERNS = -FILTER_SOURCE_FILES = NO -FILTER_SOURCE_PATTERNS = -USE_MDFILE_AS_MAINPAGE = -DISTRIBUTE_GROUP_DOC = YES - -#--------------------------------------------------------------------------- -# Configuration options related to the preprocessor -#--------------------------------------------------------------------------- -ENABLE_PREPROCESSING = YES -MACRO_EXPANSION = YES -EXPAND_ONLY_PREDEF = YES -SEARCH_INCLUDES = YES -INCLUDE_PATH = ../ -INCLUDE_FILE_PATTERNS = - -PREDEFINED = \ - BOOST_FORCEINLINE \ - BOOST_JSON_CLASS_DECL \ - BOOST_JSON_DECL \ - BOOST_JSON_DOCS \ - BOOST_JSON_PUBLIC \ - BOOST_SYMBOL_VISIBLE \ - "BOOST_JSON_INLINE_VARIABLE(v, t)=constexpr t v;" \ - "BOOST_JSON_NODISCARD=[[nodiscard]]" \ - "BOOST_JSON_NS_BEGIN=namespace boost { namespace json {" \ - "BOOST_JSON_NS_END=}}" - -EXPAND_AS_DEFINED = -SKIP_FUNCTION_MACROS = YES - -#--------------------------------------------------------------------------- -# Project related configuration options -#--------------------------------------------------------------------------- -DOXYFILE_ENCODING = UTF-8 -PROJECT_NAME = "JSON" -PROJECT_NUMBER = -PROJECT_BRIEF = JSON Library -PROJECT_LOGO = -OUTPUT_DIRECTORY = -CREATE_SUBDIRS = NO -#####ALLOW_UNICODE_NAMES = NO -OUTPUT_LANGUAGE = English -BRIEF_MEMBER_DESC = YES -REPEAT_BRIEF = YES -ABBREVIATE_BRIEF = -ALWAYS_DETAILED_SEC = NO -INLINE_INHERITED_MEMB = YES -FULL_PATH_NAMES = YES -#STRIP_FROM_PATH = $(LIB_DIR)/include # Requires doxygen 1.8.7+ -STRIP_FROM_INC_PATH = -SHORT_NAMES = NO -JAVADOC_AUTOBRIEF = YES -QT_AUTOBRIEF = NO -MULTILINE_CPP_IS_BRIEF = NO -INHERIT_DOCS = YES -SEPARATE_MEMBER_PAGES = NO -TAB_SIZE = 4 -TCL_SUBST = -OPTIMIZE_OUTPUT_FOR_C = NO -OPTIMIZE_OUTPUT_JAVA = NO -OPTIMIZE_FOR_FORTRAN = NO -OPTIMIZE_OUTPUT_VHDL = NO -EXTENSION_MAPPING = -MARKDOWN_SUPPORT = YES -AUTOLINK_SUPPORT = NO -BUILTIN_STL_SUPPORT = NO -CPP_CLI_SUPPORT = NO -SIP_SUPPORT = NO -IDL_PROPERTY_SUPPORT = YES -#####GROUP_NESTED_COMPOUNDS = NO -SUBGROUPING = YES -INLINE_GROUPED_CLASSES = NO -INLINE_SIMPLE_STRUCTS = NO -TYPEDEF_HIDES_STRUCT = NO -LOOKUP_CACHE_SIZE = 0 - -#--------------------------------------------------------------------------- -# Build related configuration options -#--------------------------------------------------------------------------- -EXTRACT_ALL = YES -EXTRACT_PRIVATE = YES -EXTRACT_PACKAGE = NO -EXTRACT_STATIC = NO -EXTRACT_LOCAL_CLASSES = NO -EXTRACT_LOCAL_METHODS = NO -EXTRACT_ANON_NSPACES = NO -HIDE_UNDOC_MEMBERS = NO -HIDE_UNDOC_CLASSES = NO -HIDE_FRIEND_COMPOUNDS = NO -HIDE_IN_BODY_DOCS = NO -INTERNAL_DOCS = NO -CASE_SENSE_NAMES = YES -HIDE_SCOPE_NAMES = NO -#####HIDE_COMPOUND_REFERENCE= NO -SHOW_INCLUDE_FILES = NO -SHOW_GROUPED_MEMB_INC = NO -FORCE_LOCAL_INCLUDES = NO -INLINE_INFO = NO -SORT_MEMBER_DOCS = NO -SORT_BRIEF_DOCS = NO -SORT_MEMBERS_CTORS_1ST = YES -SORT_GROUP_NAMES = NO -SORT_BY_SCOPE_NAME = NO -STRICT_PROTO_MATCHING = NO -GENERATE_TODOLIST = NO -GENERATE_TESTLIST = NO -GENERATE_BUGLIST = NO -GENERATE_DEPRECATEDLIST= NO -ENABLED_SECTIONS = -MAX_INITIALIZER_LINES = 30 -SHOW_USED_FILES = NO -SHOW_FILES = NO -SHOW_NAMESPACES = NO -FILE_VERSION_FILTER = -LAYOUT_FILE = -CITE_BIB_FILES = - -#--------------------------------------------------------------------------- -# Configuration options related to warning and progress messages -#--------------------------------------------------------------------------- -QUIET = NO -WARNINGS = YES -WARN_IF_UNDOCUMENTED = YES -WARN_IF_DOC_ERROR = YES -WARN_NO_PARAMDOC = NO -#####WARN_AS_ERROR = NO -WARN_FORMAT = "$file:$line: $text" -WARN_LOGFILE = - -#--------------------------------------------------------------------------- -# Configuration options related to source browsing -#--------------------------------------------------------------------------- -SOURCE_BROWSER = NO -INLINE_SOURCES = NO -STRIP_CODE_COMMENTS = YES -REFERENCED_BY_RELATION = NO -REFERENCES_RELATION = NO -REFERENCES_LINK_SOURCE = YES -SOURCE_TOOLTIPS = YES -USE_HTAGS = NO -VERBATIM_HEADERS = YES -CLANG_ASSISTED_PARSING = NO -CLANG_OPTIONS = - -#--------------------------------------------------------------------------- -# Configuration options related to the alphabetical class index -#--------------------------------------------------------------------------- -ALPHABETICAL_INDEX = YES -COLS_IN_ALPHA_INDEX = 5 -IGNORE_PREFIX = - -#--------------------------------------------------------------------------- -# Configuration options related to the HTML output -#--------------------------------------------------------------------------- -GENERATE_HTML = NO -HTML_OUTPUT = dhtm -HTML_FILE_EXTENSION = .html -HTML_HEADER = -HTML_FOOTER = -HTML_STYLESHEET = -HTML_EXTRA_STYLESHEET = -HTML_EXTRA_FILES = -HTML_COLORSTYLE_HUE = 220 -HTML_COLORSTYLE_SAT = 100 -HTML_COLORSTYLE_GAMMA = 80 -HTML_TIMESTAMP = NO -HTML_DYNAMIC_SECTIONS = NO -HTML_INDEX_NUM_ENTRIES = 100 -GENERATE_DOCSET = NO -DOCSET_FEEDNAME = "Doxygen generated docs" -DOCSET_BUNDLE_ID = org.doxygen.Project -DOCSET_PUBLISHER_ID = org.doxygen.Publisher -DOCSET_PUBLISHER_NAME = Publisher -GENERATE_HTMLHELP = NO -CHM_FILE = -HHC_LOCATION = -GENERATE_CHI = NO -CHM_INDEX_ENCODING = -BINARY_TOC = NO -TOC_EXPAND = NO -GENERATE_QHP = NO -QCH_FILE = -QHP_NAMESPACE = org.doxygen.Project -QHP_VIRTUAL_FOLDER = doc -QHP_CUST_FILTER_NAME = -QHP_CUST_FILTER_ATTRS = -QHP_SECT_FILTER_ATTRS = -QHG_LOCATION = -GENERATE_ECLIPSEHELP = NO -ECLIPSE_DOC_ID = org.doxygen.Project -DISABLE_INDEX = NO -GENERATE_TREEVIEW = NO -ENUM_VALUES_PER_LINE = 4 -TREEVIEW_WIDTH = 250 -EXT_LINKS_IN_WINDOW = NO -FORMULA_FONTSIZE = 10 -FORMULA_TRANSPARENT = YES -USE_MATHJAX = NO -MATHJAX_FORMAT = HTML-CSS -MATHJAX_RELPATH = http://cdn.mathjax.org/mathjax/latest -MATHJAX_EXTENSIONS = -MATHJAX_CODEFILE = -SEARCHENGINE = YES -SERVER_BASED_SEARCH = NO -EXTERNAL_SEARCH = NO -SEARCHENGINE_URL = -SEARCHDATA_FILE = searchdata.xml -EXTERNAL_SEARCH_ID = -EXTRA_SEARCH_MAPPINGS = - -GENERATE_LATEX = NO -GENERATE_RTF = NO -GENERATE_MAN = NO -GENERATE_DOCBOOK = NO -GENERATE_AUTOGEN_DEF = NO -GENERATE_PERLMOD = NO -CLASS_DIAGRAMS = NO -HAVE_DOT = NO - -#--------------------------------------------------------------------------- -# Configuration options related to the XML output -#--------------------------------------------------------------------------- -GENERATE_XML = YES -XML_OUTPUT = $(XML_OUTPUT) -XML_PROGRAMLISTING = YES - -#--------------------------------------------------------------------------- -# Configuration options related to external references -#--------------------------------------------------------------------------- -TAGFILES = -GENERATE_TAGFILE = -ALLEXTERNALS = NO -EXTERNAL_GROUPS = YES -EXTERNAL_PAGES = YES -PERL_PATH = /usr/bin/perl