-
Notifications
You must be signed in to change notification settings - Fork 214
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
feat: enhance and fix documentation #1310
Merged
barendgehrels
merged 1 commit into
boostorg:develop
from
barendgehrels:feat/fix-and-enhance-documentation
Sep 27, 2024
Merged
Changes from all commits
Commits
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
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.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@Lastique also for your information ('ll refer to it from elsewhere)