-
Notifications
You must be signed in to change notification settings - Fork 216
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
1 parent
68f5b99
commit 218bc06
Showing
39 changed files
with
329 additions
and
1,584 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,22 @@ | ||
| # =========================================================================== | ||
| # 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/*.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 |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,153 @@ | ||
| # =========================================================================== | ||
| # 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. | ||
| # | ||
| # The following software must be in your path: | ||
| # - doxygen | ||
| # - xsltproc | ||
| # - python3 | ||
| # - doxygen_xml2qbk (provided by Boost.Geometry) | ||
| # - quickbook (should be made, it is referred to in a relative path) | ||
| # | ||
| # Execute the script from .../boost/libs/geometry/doc | ||
|
|
||
| echo "=== Generating documentation for Boost.Geometry" | ||
|
|
||
| base=`pwd` | ||
| boost_root=`realpath ${base}/../../..` | ||
|
|
||
| # Set the DocBook (and dtd and boost dtd, less relevant) versions. | ||
|
|
||
| # 1.75.2 is the one setup within Boost for ages. | ||
| # It reports as debug message: "Computing chunks..." | ||
| # But it currently gives the error message | ||
| # "The called template 'id.attribute' was not found." | ||
| # For all libraries (not only Boost.Geometry) | ||
|
|
||
| # 1.79.1 works and gives correct documentation | ||
| # It does not output any extra debug message | ||
|
|
||
| # 1.79.2 (with namespaces, on mac) gives empty content for sub-toc pages for Boost.Geometry | ||
| # It reports as debug message: "Note: namesp. add : added namespace before processing Geometry" | ||
| # 1.79.2 ("nons", no namespace) works and gives correct documentation | ||
| # It can be downloaded from https://www.linuxfromscratch.org/blfs/view/stable/pst/docbook-xsl.html | ||
|
|
||
| # Set the values with 4.2 / 1.75.2 - used by setup_boostbook.sh | ||
| docbook_dtd_version=4.2 | ||
| docbook_xsl_version=1.75.2 | ||
| docbook_dtd=${boost_root}/tools/boostbook/docbook-dtd-${docbook_dtd_version} | ||
| docbook_xsl=${boost_root}/tools/boostbook/docbook-xsl-${docbook_xsl_version} | ||
|
|
||
| # OVERRIDE the values with 4.5 / 1.79.1 - used by boostorg/release-tools/blob/develop/build_docs | ||
| docbook_dtd_version=4.5 | ||
| docbook_xsl_version=1.79.1 | ||
| docbook_dtd=~/data/docbook/docbook-dtd-${docbook_dtd_version} | ||
| docbook_xsl=~/data/docbook/docbook-xsl-${docbook_xsl_version} | ||
|
|
||
| # UNCOMMENT the values with 4.5 / 1.79.2 - for future usage, note the "nons", which is essential | ||
| # docbook_xsl_version=1.79.2 | ||
| # docbook_xsl=~/data/docbook/docbook-xsl-nons-${docbook_xsl_version} | ||
|
|
||
| # Set other values of dtd, css, style sheets | ||
| boostbook_dtd=${boost_root}/tools/boostbook/dtd | ||
|
|
||
| file_css=${boost_root}/doc/src/boostbook.css | ||
|
|
||
| xsl_docbook=${boost_root}/tools/boostbook/xsl/docbook.xsl | ||
| xsl_html=${boost_root}/tools/boostbook/xsl/html.xsl | ||
|
|
||
| # Set the folder where to generate boostbook/docbook and some filenames | ||
| folder_generated=generated | ||
| file_boostbook=${folder_generated}/geometry.boostbook.xml | ||
| file_docbook=${folder_generated}/geometry.docbook.xml | ||
|
|
||
| # === step 1 === | ||
|
|
||
| echo "=== Running Doxygen" | ||
| cd doxy | ||
| doxygen Doxyfile | ||
| cd .. | ||
|
|
||
| # === step 2 === | ||
| # Note that doxygen_xml2qbk should be in your path! | ||
|
|
||
| echo "=== From Doxygen XML to QuickBook" | ||
| python3 make_qbk.py --skip_doxygen | ||
|
|
||
| # === step 3 === | ||
|
|
||
| echo "=== From QuickBook to BoostBook" | ||
| ${boost_root}/dist/bin/quickbook -I"${boost_root}" -I"." -D"enable_index" \ | ||
| --output-file=${file_boostbook} geometry.qbk | ||
|
|
||
| # === step 4 === | ||
|
|
||
| # To avoid using b2 and user-config.jam, the catalog has to be written locally | ||
| filename_catalog=${folder_generated}/catalog.xml | ||
| echo "=== Write ${filename_catalog} for xstlproc with ${docbook_xsl}" | ||
|
|
||
| cat <<EOF >${filename_catalog} | ||
| <?xml version="1.0"?> | ||
| <!DOCTYPE catalog | ||
| PUBLIC "-//OASIS/DTD Entity Resolution XML Catalog V1.0//EN" | ||
| "http://www.oasis-open.org/committees/entity/release/1.0/catalog.dtd"> | ||
| <catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog"> | ||
| <rewriteURI uriStartString="http://www.boost.org/tools/boostbook/dtd/" rewritePrefix="file:///${boostbook_dtd}/"/> | ||
| <rewriteURI uriStartString="http://www.oasis-open.org/docbook/xml/${docbook_dtd_version}/" rewritePrefix="file:///${docbook_dtd}/"/> | ||
| <rewriteURI uriStartString="http://docbook.sourceforge.net/release/xsl/current/" rewritePrefix="file:///${docbook_xsl}/"/> | ||
| </catalog> | ||
| EOF | ||
|
|
||
| # It is necessary to publish its location in an environment variable | ||
| export XML_CATALOG_FILES=${filename_catalog} | ||
|
|
||
| # Set parameters shared for Boostbook -> Docbook -> HTML | ||
| params="--xinclude" | ||
| params="${params} --stringparam boost.defaults Boost" | ||
|
|
||
| # Set boost.root (here, it should be relative, and go one above boost root itself) | ||
| params="${params} --stringparam boost.root ../../../.." | ||
|
|
||
| echo "=== From BoostBook to DocBook" | ||
| xsltproc ${params} --path ${folder_generated} -o ${file_docbook} ${xsl_docbook} ${file_boostbook} | ||
|
|
||
| # === step 5 === | ||
|
|
||
| # These parameters define behaviour for DocBook. | ||
| # See also https://www.sagehill.net/docbookxsl/TOCcontrol.html | ||
| # The parameters values should correspond with the values in Jamfile. | ||
|
|
||
| # Their values are currently valid for docbook-xsl-1.75.2 (the version included in Boost). | ||
| # However, the sections.xsl file currently included boost do not work for 1.75.2 | ||
| # If this is encountered, remove the part "<xsl:call-template name="id.attribute">" | ||
|
|
||
| # Their values are currently also valid for version 1.79.1 | ||
| # But for version 1.79.2 is used, the chunking is broken. | ||
|
|
||
| chunk_section_depth=4 | ||
| chunk_first_sections=1 | ||
| toc_section_depth=3 | ||
| toc_max_depth=2 | ||
| generate_section_toc_level=4 | ||
|
|
||
| params="${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 ${params} --path ${folder_generated} -o "html/" ${xsl_html} ${file_docbook} | ||
|
|
||
| echo "=== Resulting html, generated with:" | ||
| cat html/index.html| grep -w -e generator | ||
|
|
||
| echo "=== Resulting contents of generated 'adapted.html', there should be sections" | ||
| cat html/geometry/reference/adapted.html | grep section | ||
|
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.