Skip to content

Commit

Permalink
feat: enhance and fix documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
barendgehrels committed Sep 22, 2024
1 parent 6c17350 commit adb1509
Show file tree
Hide file tree
Showing 39 changed files with 239 additions and 1,584 deletions.
1 change: 1 addition & 0 deletions doc/Jamfile
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,7 @@ testing.make-test run-pyd :
:
<pythonpath>$(here)
<dependency>src/docutils/tools/doxygen_xml2qbk//doxygen_xml2qbk
<dependency>doxy/Doxyfile
<testing.arg>"--release-build --doxygen-xml2qbk"
<testing.input-file>src/docutils/tools/doxygen_xml2qbk//doxygen_xml2qbk
:
Expand Down
2 changes: 1 addition & 1 deletion doc/concept/point.qbk
Original file line number Diff line number Diff line change
Expand Up @@ -68,7 +68,7 @@ struct access<std::array<T, D>, Index> {
* [link geometry.reference.adapted.boost_fusion Boost.Fusion]
* [link geometry.reference.adapted.boost_polygon Boost.Polygon]
* [link geometry.reference.adapted.boost_tuple Boost.Tuple]
* other point types, adapted e.g. using one of the [link geometry.reference.adapted registration macro's]
* other point types, adapted e.g. using one of the [link geometry.reference.adapted.register registration macro's]

[endsect]

Expand Down
23 changes: 23 additions & 0 deletions doc/debug_clean_doc.sh
Original file line number Diff line number Diff line change
@@ -0,0 +1,23 @@
# ===========================================================================
# Copyright (c) 2024-2024 Barend Gehrels, Amsterdam, the Netherlands.
#
# Use, modification and distribution is subject to 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)
# ============================================================================

# Removes all generated output

b2 clean

rm -f index/generated/*.qbk
rm -f generated/*.qbk
rm -f generated/geometry.docbook
rm -f generated/geometry.xml
rm -Rf html/geometry
rm -Rf doxy/doxygen_output/xml
rm -Rf doxy/doxygen_output/html_by_doxygen
rm -Rf index/xml
rm -Rf index/html_by_doxygen

git ls-files --others
62 changes: 62 additions & 0 deletions doc/debug_make_doc.sh
Original file line number Diff line number Diff line change
@@ -0,0 +1,62 @@
# ===========================================================================
# Copyright (c) 2024-2024 Barend Gehrels, Amsterdam, the Netherlands.
#
# Use, modification and distribution is subject to 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)
# ============================================================================

# Makes the documentation without calling b2, to be able to do it in steps
# and debug the individual steps.

GENERATED_FOLDER=generated
export XML_CATALOG_FILES="../../../bin.v2/boostbook_catalog.xml"

echo "=== Running Doxygen"
cd doxy
doxygen Doxyfile
cd ..

echo "=== From Doxygen XML to QuickBook"
python3 make_qbk.py --skip_doxygen

echo "=== From QuickBook to BoostBook"
../../../dist/bin/quickbook -I"../../.." -I"." -D"enable_index" \
--output-file=${GENERATED_FOLDER}/geometry.xml geometry.qbk

echo "=== From BoostBook to DocBook"
xsltproc --stringparam boost.defaults "Boost" \
--stringparam boost.root "../../../.." \
--path "${GENERATED_FOLDER}" \
--xinclude \
-o "${GENERATED_FOLDER}/geometry.docbook" \
"../../../tools/boostbook/xsl/docbook.xsl" \
"${GENERATED_FOLDER}/geometry.xml"

# These parameters define behaviour for DocBook. Note that they are valid
# for docbook-xsl-1.75.2 (the version included in Boost). If a later version
# is used, the chunking is broken.
# Their values should correspond with the values in Jamfile.
# Note also that the sections.xsl file currently included boost might not work.
# If this is encountered, remove the part "<xsl:call-template name="id.attribute">"
chunk_section_depth=4
chunk_first_sections=1
toc_section_depth=3
toc_max_depth=2
generate_section_toc_level=4

params="--stringparam chunk.section.depth ${chunk_section_depth}"
params="${params} --stringparam chunk.first.sections ${chunk_first_sections}"
params="${params} --stringparam toc.max.depth ${toc_max_depth}"
params="${params} --stringparam toc.section.depth ${toc_section_depth}"
params="${params} --stringparam generate.section.toc.level ${generate_section_toc_level}"

echo "=== From DocBook to html"
xsltproc --stringparam boost.defaults "Boost" \
--stringparam boost.root "../../../.." \
${params} \
--path "${GENERATED_FOLDER}" \
--xinclude \
-o "html/" \
"../../../tools/boostbook/xsl/html.xsl" \
"${GENERATED_FOLDER}/geometry.docbook"
54 changes: 30 additions & 24 deletions doc/doxy/Doxyfile
Original file line number Diff line number Diff line change
Expand Up @@ -5,19 +5,19 @@
#---------------------------------------------------------------------------
DOXYFILE_ENCODING = UTF-8
PROJECT_NAME = "Boost.Geometry (aka GGL)"
PROJECT_NUMBER =
PROJECT_NUMBER =
OUTPUT_DIRECTORY = ./doxygen_output
CREATE_SUBDIRS = NO
OUTPUT_LANGUAGE = English
BRIEF_MEMBER_DESC = YES
REPEAT_BRIEF = YES
ABBREVIATE_BRIEF =
ABBREVIATE_BRIEF =
ALWAYS_DETAILED_SEC = YES
INLINE_INHERITED_MEMB = NO
FULL_PATH_NAMES = YES
STRIP_FROM_PATH = c:/_svn/boost/trunk/boost/geometry \
c:/_svn/boost/trunk/libs/geometry/doc/doxygen_input/pages
STRIP_FROM_INC_PATH =
STRIP_FROM_INC_PATH =
SHORT_NAMES = NO
JAVADOC_AUTOBRIEF = NO
QT_AUTOBRIEF = NO
Expand All @@ -26,7 +26,7 @@ INHERIT_DOCS = YES
SEPARATE_MEMBER_PAGES = NO
TAB_SIZE = 8

# The aliases are shortcuts for Doxygen documentation.
# The aliases are shortcuts for Doxygen documentation.
# Within Boost.Geometry they are used in the top section, so for both
# Doxygen documentation and QuickBook documentation.
# They avoid repetations and make the documentation more structured.
Expand All @@ -39,6 +39,8 @@ TAB_SIZE = 8
# \return* for various return cases
ALIASES = qbk{1}="\xmlonly <qbk>\1</qbk> \endxmlonly" \
qbk{2}="\xmlonly <qbk.\1>\2</qbk.\1> \endxmlonly" \
wkt="WKT" \
well_known_text="Well-Known Text" \
brief_calc{1}="Calculates the \1 of a geometry" \
brief_calc2{1}="Calculate the \1 of two geometries" \
brief_calc2{2}="Calculate the \1 \2 two geometries" \
Expand Down Expand Up @@ -101,9 +103,10 @@ ALIASES = qbk{1}="\xmlonly <qbk>\1</qbk> \endxmlonly" \
details_calc2{1}="The free function \1 calculates the \1 of two geometries" \
details_check12{2}="The free function \1 checks if the first geometry \2 the second geometry" \
details_macro{2}="The macro \1 registers a \2 such that it is recognized by Boost.Geometry and that Boost.Geometry functionality can used with the specified type." \
details_macro_const="The const version registers only read access to the fields, the point type is therefore read-only" \
details_macro_getset="The get/set version registers get and set methods separately and can be used for classes with protected member variables and get/set methods to change coordinates" \
details_macro_const="The const version registers only read access to the fields, the point type is therefore read-only." \
details_macro_getset="The get/set version registers get and set methods separately and can be used for classes with protected member variables and get/set methods to change coordinates." \
details_macro_templated{2}="The type must have one template parameter, which should be a \2 type, and should not be specified. Boost.Geometry takes care of inserting the template parameter. Hence all types of this templated \1 are registered, regardless of their point type." \
details_macro_lola="For geographic coordinate systems, be sure to specify first longitude and then latitude, to be able to use the strategies included in the library." \
details_default_strategy="It uses the default strategy, based on the coordinate system of the geometry." \
details_strategy_reasons="Reasons to specify a strategy include: use another coordinate system for calculations; construct the strategy beforehand (e.g. with the radius of the Earth); select a strategy when there are more than one available for a calculation." \
details_return{1}="This version with the return_ prefix returns the \1, and a template parameter must therefore be specified in the call." \
Expand All @@ -124,6 +127,8 @@ ALIASES = qbk{1}="\xmlonly <qbk>\1</qbk> \endxmlonly" \
macro_x="first (usually x)" \
macro_y="second (usually y)" \
macro_z="third (usually z)" \
macro_x_lon="first (usually x, or longitude)" \
macro_y_lat="second (usually y, or latitude)" \
p_l_or_c="Point, LineString or Polygon"
OPTIMIZE_OUTPUT_FOR_C = NO
OPTIMIZE_OUTPUT_JAVA = NO
Expand Down Expand Up @@ -161,10 +166,10 @@ GENERATE_TODOLIST = NO
GENERATE_TESTLIST = YES
GENERATE_BUGLIST = YES
GENERATE_DEPRECATEDLIST= YES
ENABLED_SECTIONS =
ENABLED_SECTIONS =
MAX_INITIALIZER_LINES = 30
SHOW_USED_FILES = NO
FILE_VERSION_FILTER =
FILE_VERSION_FILTER =
#---------------------------------------------------------------------------
# configuration options related to warning and progress messages
#---------------------------------------------------------------------------
Expand All @@ -174,7 +179,7 @@ WARN_IF_UNDOCUMENTED = YES
WARN_IF_DOC_ERROR = YES
WARN_NO_PARAMDOC = NO
WARN_FORMAT = "$file:$line: $text"
WARN_LOGFILE =
WARN_LOGFILE =
#---------------------------------------------------------------------------
# configuration options related to the input files
#---------------------------------------------------------------------------
Expand Down Expand Up @@ -227,7 +232,6 @@ INPUT = . .. ../../../../boost/geometry/core \
../../../../boost/geometry/strategy/spherical \
../../../../boost/geometry/util \
../../../../boost/geometry/views \
./doxygen_input/pages \
./doxygen_input/groups
INPUT_ENCODING = UTF-8
FILE_PATTERNS = *.hpp
Expand All @@ -239,19 +243,19 @@ EXCLUDE = ../../../../boost/geometry/util/builder.hpp \
../../../../boost/geometry/util/distance_sort.hpp \
./doxygen_extension_examples.hpp
EXCLUDE_SYMLINKS = NO
EXCLUDE_PATTERNS =
EXCLUDE_SYMBOLS =
EXCLUDE_PATTERNS =
EXCLUDE_SYMBOLS =
EXAMPLE_PATH = . .. ../../example ../../example/with_external_libs \
doxygen_input/sourcecode \
../../../../boost/geometry/geometries \
../../../../boost/geometry/strategies \
../../../../boost/geometry/strategies/cartesian \
../../../../boost/geometry/algorithms
EXAMPLE_PATTERNS =
EXAMPLE_PATTERNS =
EXAMPLE_RECURSIVE = NO
IMAGE_PATH = doxygen_input/images
INPUT_FILTER =
FILTER_PATTERNS =
INPUT_FILTER =
FILTER_PATTERNS =
FILTER_SOURCE_FILES = NO
#---------------------------------------------------------------------------
# configuration options related to source browsing
Expand All @@ -268,23 +272,25 @@ VERBATIM_HEADERS = NO
# configuration options related to the alphabetical class index
#---------------------------------------------------------------------------
COLS_IN_ALPHA_INDEX = 3
IGNORE_PREFIX =
IGNORE_PREFIX =
#---------------------------------------------------------------------------
# configuration options related to the HTML output
# This is only for debug purposes. For the final documentation, XML output is
# converted to QuickBook and then to BoostBook and DocBook and html
#---------------------------------------------------------------------------
GENERATE_HTML = YES
HTML_OUTPUT = html_by_doxygen
HTML_FILE_EXTENSION = .html
HTML_HEADER = doxygen_input/ggl_doxygen_header.html
HTML_FOOTER = doxygen_input/ggl_doxygen_footer.html
HTML_STYLESHEET =
HTML_STYLESHEET =
GENERATE_HTMLHELP = NO
GENERATE_DOCSET = NO
DOCSET_FEEDNAME = "Generated documentation, by Doxygen"
DOCSET_BUNDLE_ID = org.doxygen.Project
HTML_DYNAMIC_SECTIONS = NO
CHM_FILE =
HHC_LOCATION =
CHM_FILE =
HHC_LOCATION =
GENERATE_CHI = NO
BINARY_TOC = NO
TOC_EXPAND = NO
Expand All @@ -311,14 +317,14 @@ GENERATE_PERLMOD = NO


#---------------------------------------------------------------------------
# Configuration options related to the preprocessor
# Configuration options related to the preprocessor
#---------------------------------------------------------------------------
ENABLE_PREPROCESSING = YES
MACRO_EXPANSION = YES
EXPAND_ONLY_PREDEF = YES
SEARCH_INCLUDES = YES
INCLUDE_PATH =
INCLUDE_FILE_PATTERNS =
INCLUDE_PATH =
INCLUDE_FILE_PATTERNS =
PREDEFINED = BOOST_CONCEPT_REQUIRES(x) \
BOOST_CONCEPT_ASSERT(x) \
BOOST_STATIC_ASSERT(x) \
Expand All @@ -331,12 +337,12 @@ PREDEFINED = BOOST_CONCEPT_REQUIRES(x) \
DOXYGEN_NO_STRATEGY_SPECIALIZATIONS \
DOXYGEN_NO_SPECIALIZATIONS \
DOXYGEN_INVOKED
EXPAND_AS_DEFINED =
EXPAND_AS_DEFINED =
SKIP_FUNCTION_MACROS = YES


#---------------------------------------------------------------------------
# Configuration::additions related to the search engine
# Configuration::additions related to the search engine
#---------------------------------------------------------------------------
SEARCHENGINE = NO

Expand Down
33 changes: 0 additions & 33 deletions doc/doxy/doxygen_enhance.py

This file was deleted.

Loading

0 comments on commit adb1509

Please sign in to comment.