From f8a325543ca9fef26cb4dfb744829ad04a51b18a Mon Sep 17 00:00:00 2001 From: Julio Estrada Date: Tue, 16 Dec 2025 16:18:29 -0500 Subject: [PATCH 1/8] WIP: Add tools section to Boost library views and templates - Introduced a new TOOLS constant in constants.py containing various Boost tools with descriptions and URLs. - Implemented a get_tools function in utils.py to retrieve and sort the tools. - Updated LibraryListBase to include tools in the context data for library views. - Enhanced categorized_list.html, grid_list.html, and vertical_list.html templates to display tools alongside libraries, with appropriate descriptions and formatting. --- libraries/constants.py | 44 +++++++++++++++++++ libraries/utils.py | 19 ++++++++ libraries/views.py | 19 ++++++++ .../_tool_categorized_list_item.html | 28 ++++++++++++ templates/libraries/_tool_grid_list_item.html | 23 ++++++++++ .../libraries/_tool_vertical_list_item.html | 27 ++++++++++++ templates/libraries/categorized_list.html | 14 +++++- templates/libraries/grid_list.html | 12 +++++ templates/libraries/vertical_list.html | 14 ++++++ 9 files changed, 198 insertions(+), 2 deletions(-) create mode 100644 templates/libraries/_tool_categorized_list_item.html create mode 100644 templates/libraries/_tool_grid_list_item.html create mode 100644 templates/libraries/_tool_vertical_list_item.html diff --git a/libraries/constants.py b/libraries/constants.py index 51d2fbcbc..18ed65f6a 100644 --- a/libraries/constants.py +++ b/libraries/constants.py @@ -369,3 +369,47 @@ DOCKER_CONTAINER_URL_WEB = "http://web:8000" RELEASE_REPORT_AUTHORS_PER_PAGE_THRESHOLD = 6 +TOOLS = [ + { + "name": "Boost.Build", + "slug": "build", + "description": "The Boost build system, including the full Boost version of the jam sources.", + "url": "libs/latest/tools/build/doc/html/index.html", + }, + { + "name": "Regression", + "slug": "regression", + "description": "The Boost regression testing system reporting sources.", + "url": "tools/regression/index.html", + }, + { + "name": "Inspect", + "slug": "inspect", + "description": "The inspection tool used to detect errors in the Boost directory hierarchy.", + "url": "tools/inspect/index.html", + }, + { + "name": "BoostBook", + "slug": "boostbook", + "description": "A Boost documentation system, based on DocBook and the Extensible Stylesheet Language (XSL), used by some Boost libraries.", + "url": "tools/boostbook/index.html", + }, + { + "name": "bcp", + "slug": "bcp", + "description": "A utility to extract subsets of Boost; to determine which parts of Boost your code is using; and to print reports on Boost usage (including Licence information).", + "url": "tools/bcp/", + }, + { + "name": "QuickBook", + "slug": "quickbook", + "description": "QuickBook is a WikiWiki style documentation tool geared towards C++ documentation using simple rules and markup for simple formatting tasks. QuickBook generates BoostBook XML.", + "url": "", + }, + { + "name": "Wave", + "slug": "wave", + "description": "A Standards conformant C/C++ preprocessor usable on top of any other compiler. Usable for instance for the debugging of the expansion of macros in your code or as a replacement for your built-in preprocessor.", + "url": "", + }, +] diff --git a/libraries/utils.py b/libraries/utils.py index cdb88f029..1420613b9 100644 --- a/libraries/utils.py +++ b/libraries/utils.py @@ -19,6 +19,7 @@ LEGACY_LATEST_RELEASE_URL_PATH_STR, DEVELOP_RELEASE_URL_PATH_STR, MASTER_RELEASE_URL_PATH_STR, + TOOLS, ) from versions.models import Version @@ -370,3 +371,21 @@ def generate_release_report_filename(version_slug: str, published_format: bool = filename_data.append(datetime.now(timezone.utc).isoformat()) filename = f"{'-'.join(filename_data)}.pdf" return filename + + +def get_tools(): + """ + Return list of tool dictionaries. + + Tools are utilities used by Boost developers and users, + separate from libraries. They appear alongside libraries + in library list views. + + Returns: + list: List of tool dictionaries with keys: + - name: str + - slug: str + - description: str + - url: str + """ + return sorted(TOOLS.copy(), key=lambda tool: tool["name"].lower()) diff --git a/libraries/views.py b/libraries/views.py index a11c146a7..55fb0df73 100644 --- a/libraries/views.py +++ b/libraries/views.py @@ -35,6 +35,7 @@ get_documentation_url_redirect, get_prioritized_version, get_version_from_cookie, + get_tools, ) from .constants import LATEST_RELEASE_URL_PATH_STR @@ -104,6 +105,7 @@ def get_queryset(self): def get_context_data(self, **kwargs): context = super().get_context_data(**self.kwargs) context["categories"] = self.get_categories(context["selected_version"]) + context["tools"] = get_tools() # todo: add tests for sort order if self.kwargs.get("category_slug"): context["category"] = Category.objects.get( @@ -210,6 +212,23 @@ def get_results_by_category(self, version: Version | None): results_by_category.append( {"category": category, "library_version_list": library_versions} ) + + # Add tools as a separate category + tools = get_tools() + if tools: + # Create a simple object for tools category + class ToolsCategory: + name = "Tools" + slug = "tools" + + results_by_category.append( + { + "category": ToolsCategory(), + "library_version_list": [], + "tools": tools, + } + ) + return results_by_category diff --git a/templates/libraries/_tool_categorized_list_item.html b/templates/libraries/_tool_categorized_list_item.html new file mode 100644 index 000000000..759dc176e --- /dev/null +++ b/templates/libraries/_tool_categorized_list_item.html @@ -0,0 +1,28 @@ + + + {% if tool.url %} + {{ tool.name }} + {% else %} + {{ tool.name }} + {% endif %} + + + + {# Empty cell for alignment with library rows #} + + + {# Empty cell for alignment with library rows #} + + + {% if tool.url %} + + + + {% endif %} + + {{ tool.description }} + + + {{ tool.description }} + diff --git a/templates/libraries/_tool_grid_list_item.html b/templates/libraries/_tool_grid_list_item.html new file mode 100644 index 000000000..d0d7b3cb6 --- /dev/null +++ b/templates/libraries/_tool_grid_list_item.html @@ -0,0 +1,23 @@ +{% load static %} + +
+
+

+
+ {% if tool.url %} + {{ tool.name }} + {% else %} + {{ tool.name }} + {% endif %} + {% if tool.url %} + + + + {% endif %} +
+

+
+
+

{{ tool.description }}

+
+
diff --git a/templates/libraries/_tool_vertical_list_item.html b/templates/libraries/_tool_vertical_list_item.html new file mode 100644 index 000000000..0f938e340 --- /dev/null +++ b/templates/libraries/_tool_vertical_list_item.html @@ -0,0 +1,27 @@ + + + {% if tool.url %} + {{ tool.name }} + {% else %} + {{ tool.name }} + {% endif %} + + + {# Empty cell for alignment with library rows #} + + + {# Empty cell for alignment with library rows #} + + + {% if tool.url %} + + + + {% endif %} + + {{ tool.description }} + + + {{ tool.description }} + diff --git a/templates/libraries/categorized_list.html b/templates/libraries/categorized_list.html index 89e2a0cdd..0ee9f69b4 100644 --- a/templates/libraries/categorized_list.html +++ b/templates/libraries/categorized_list.html @@ -17,14 +17,24 @@
{% for result in library_versions_by_category %}
-
{{ result.category }}
+
{{ result.category.name }}
+ {% if result.tools %} +

Boost developers, testers, and maintainers have developed various programs to help with the administration of the Boost Libraries. Like everything else about Boost, these tools are available in source form, and are part of the regular Boost distribution.

+ {% endif %} {% for library_version in result.library_version_list %} {% include "libraries/_library_categorized_list_item.html" %} {% empty %} -

No libraries in this category yet.

+ {% if not result.tools %} +

No libraries in this category yet.

+ {% endif %} {% endfor %} + {% if result.tools %} + {% for tool in result.tools %} + {% include "libraries/_tool_categorized_list_item.html" %} + {% endfor %} + {% endif %}
diff --git a/templates/libraries/grid_list.html b/templates/libraries/grid_list.html index 2b64b2f25..b0593841e 100644 --- a/templates/libraries/grid_list.html +++ b/templates/libraries/grid_list.html @@ -20,6 +20,18 @@
{# end libraries list #} + {# Tools section #} +
+

Tools

+

Boost developers, testers, and maintainers have developed various programs to help with the administration of the Boost Libraries. Like everything else about Boost, these tools are available in source form, and are part of the regular Boost distribution.

+
+ {% for tool in tools %} + {% include "libraries/_tool_grid_list_item.html" %} + {% endfor %} +
+
+ {# end tools section #} + {% if page_obj.paginator %} {# pagination #}
diff --git a/templates/libraries/vertical_list.html b/templates/libraries/vertical_list.html index 02a39a8d0..7e12b69d5 100644 --- a/templates/libraries/vertical_list.html +++ b/templates/libraries/vertical_list.html @@ -28,6 +28,20 @@
+
Tools
+

Boost developers, testers, and maintainers have developed various programs to help with the administration of the Boost Libraries. Like everything else about Boost, these tools are available in source form, and are part of the regular Boost distribution.

+ + + {% for tool in tools %} + {% include "libraries/_tool_vertical_list_item.html" %} + {% endfor %} + +
+
+ {# end tools section #} + {% if page_obj.paginator %} {# Pagination #}
From ec7e44cab74bf9d3d20725f1699c629fa4b57c95 Mon Sep 17 00:00:00 2001 From: Julio Estrada Date: Wed, 17 Dec 2025 16:23:59 -0500 Subject: [PATCH 2/8] Enhance tools functionality in Boost library - Added a new tool "boostlook" to the TOOLS constant in constants.py with its description and URL. - Modified the get_tools function in utils.py to accept an optional version parameter, allowing for dynamic URL generation for version-specific tools. - Updated LibraryListBase and LibraryCategorized views to pass the selected version to get_tools, ensuring correct URL handling in the context data. --- libraries/constants.py | 32 ++++++++++++++++++++------------ libraries/utils.py | 28 ++++++++++++++++++++++++---- libraries/views.py | 4 ++-- 3 files changed, 46 insertions(+), 18 deletions(-) diff --git a/libraries/constants.py b/libraries/constants.py index 18ed65f6a..ec15fe425 100644 --- a/libraries/constants.py +++ b/libraries/constants.py @@ -370,46 +370,54 @@ RELEASE_REPORT_AUTHORS_PER_PAGE_THRESHOLD = 6 TOOLS = [ + { + "name": "boostlook", + "description": "A CSS framework for Boost C++ Library documentation.", + "url_path": "https://github.com/boostorg/boostlook", + "version_specific": False, + }, { "name": "Boost.Build", "slug": "build", "description": "The Boost build system, including the full Boost version of the jam sources.", - "url": "libs/latest/tools/build/doc/html/index.html", + "version_specific": True, + "url_path": "tools/build/doc/html/index.html", }, { "name": "Regression", - "slug": "regression", "description": "The Boost regression testing system reporting sources.", - "url": "tools/regression/index.html", + "url_path": "https://www.boost.org/doc/contributor-guide/testing/regression-tests.html", + "version_specific": False, }, { "name": "Inspect", - "slug": "inspect", "description": "The inspection tool used to detect errors in the Boost directory hierarchy.", - "url": "tools/inspect/index.html", + "version_specific": True, + "url_path": "tools/inspect/index.html", }, { "name": "BoostBook", - "slug": "boostbook", "description": "A Boost documentation system, based on DocBook and the Extensible Stylesheet Language (XSL), used by some Boost libraries.", - "url": "tools/boostbook/index.html", + "version_specific": True, + "url_path": "tools/boostbook/index.html", }, { "name": "bcp", - "slug": "bcp", "description": "A utility to extract subsets of Boost; to determine which parts of Boost your code is using; and to print reports on Boost usage (including Licence information).", - "url": "tools/bcp/", + "version_specific": True, + "url_path": "tools/bcp/", }, { "name": "QuickBook", - "slug": "quickbook", "description": "QuickBook is a WikiWiki style documentation tool geared towards C++ documentation using simple rules and markup for simple formatting tasks. QuickBook generates BoostBook XML.", - "url": "", + "url_path": "https://www.boost.org/doc/libs/latest/doc/html/quickbook.html", + "version_specific": False, }, { "name": "Wave", "slug": "wave", "description": "A Standards conformant C/C++ preprocessor usable on top of any other compiler. Usable for instance for the debugging of the expansion of macros in your code or as a replacement for your built-in preprocessor.", - "url": "", + "version_specific": True, + "url_path": "libs/wave/index.html", }, ] diff --git a/libraries/utils.py b/libraries/utils.py index 1420613b9..b5861d56d 100644 --- a/libraries/utils.py +++ b/libraries/utils.py @@ -373,7 +373,7 @@ def generate_release_report_filename(version_slug: str, published_format: bool = return filename -def get_tools(): +def get_tools(version=None): """ Return list of tool dictionaries. @@ -381,11 +381,31 @@ def get_tools(): separate from libraries. They appear alongside libraries in library list views. + Args: + version: Optional Version object. If provided, tools with + version_specific=True will have their URLs generated + based on the version. + Returns: list: List of tool dictionaries with keys: - name: str - - slug: str - description: str - - url: str + - url: str (generated for version_specific tools if version provided) """ - return sorted(TOOLS.copy(), key=lambda tool: tool["name"].lower()) + tools = [] + for tool in TOOLS.copy(): + tool_dict = tool.copy() + url_path = tool_dict.get("url_path", "") + if tool_dict.get("version_specific"): + if version: + version_slug = version.stripped_boost_url_slug + tool_dict["url"] = ( + f"https://www.boost.org/doc/libs/{version_slug}/{url_path}" + ) + else: + tool_dict["url"] = "" + else: + # For non-version-specific tools, use url_path as-is (full URL) + tool_dict["url"] = url_path + tools.append(tool_dict) + return sorted(tools, key=lambda tool: tool["name"].lower()) diff --git a/libraries/views.py b/libraries/views.py index 55fb0df73..763439b41 100644 --- a/libraries/views.py +++ b/libraries/views.py @@ -105,7 +105,7 @@ def get_queryset(self): def get_context_data(self, **kwargs): context = super().get_context_data(**self.kwargs) context["categories"] = self.get_categories(context["selected_version"]) - context["tools"] = get_tools() + context["tools"] = get_tools(version=context.get("selected_version")) # todo: add tests for sort order if self.kwargs.get("category_slug"): context["category"] = Category.objects.get( @@ -214,7 +214,7 @@ def get_results_by_category(self, version: Version | None): ) # Add tools as a separate category - tools = get_tools() + tools = get_tools(version=version) if tools: # Create a simple object for tools category class ToolsCategory: From 62db6a139533b6d28eab7045df56b575046636c5 Mon Sep 17 00:00:00 2001 From: Julio Estrada Date: Wed, 17 Dec 2025 17:09:10 -0500 Subject: [PATCH 3/8] Refactor tool list item templates for improved URL handling - Updated _tool_categorized_list_item.html, _tool_grid_list_item.html, and _tool_vertical_list_item.html to conditionally render tool URLs, allowing for clickable rows and cards. - Simplified the display logic for tool names and descriptions, ensuring consistent styling and behavior across different list formats. - Enhanced accessibility by adding cursor pointer styles for clickable elements. --- .../_tool_categorized_list_item.html | 21 +++++++---------- templates/libraries/_tool_grid_list_item.html | 23 ++++++++----------- .../libraries/_tool_vertical_list_item.html | 21 +++++++---------- 3 files changed, 25 insertions(+), 40 deletions(-) diff --git a/templates/libraries/_tool_categorized_list_item.html b/templates/libraries/_tool_categorized_list_item.html index 759dc176e..d56b4641b 100644 --- a/templates/libraries/_tool_categorized_list_item.html +++ b/templates/libraries/_tool_categorized_list_item.html @@ -1,11 +1,10 @@ - +{% if tool.url %} + +{% else %} + +{% endif %} - {% if tool.url %} - {{ tool.name }} - {% else %} - {{ tool.name }} - {% endif %} + {{ tool.name }} @@ -15,13 +14,9 @@ {# Empty cell for alignment with library rows #} - {% if tool.url %} - - - - {% endif %} + {# Empty cell for alignment with library rows #} - {{ tool.description }} + {{ tool.description }} {{ tool.description }} diff --git a/templates/libraries/_tool_grid_list_item.html b/templates/libraries/_tool_grid_list_item.html index d0d7b3cb6..54a2b6408 100644 --- a/templates/libraries/_tool_grid_list_item.html +++ b/templates/libraries/_tool_grid_list_item.html @@ -1,23 +1,18 @@ {% load static %} -
+{% if tool.url %} + +{% endif %} +

-
- {% if tool.url %} - {{ tool.name }} - {% else %} - {{ tool.name }} - {% endif %} - {% if tool.url %} - - - - {% endif %} -
+ {{ tool.name }}

-
+

{{ tool.description }}

+{% if tool.url %} + +{% endif %} diff --git a/templates/libraries/_tool_vertical_list_item.html b/templates/libraries/_tool_vertical_list_item.html index 0f938e340..e6de7a328 100644 --- a/templates/libraries/_tool_vertical_list_item.html +++ b/templates/libraries/_tool_vertical_list_item.html @@ -1,11 +1,10 @@ - +{% if tool.url %} + +{% else %} + +{% endif %} - {% if tool.url %} - {{ tool.name }} - {% else %} - {{ tool.name }} - {% endif %} + {{ tool.name }} {# Empty cell for alignment with library rows #} @@ -14,13 +13,9 @@ {# Empty cell for alignment with library rows #} - {% if tool.url %} - - - - {% endif %} + {# Empty cell for alignment with library rows #} - {{ tool.description }} + {{ tool.description }} {{ tool.description }} From 85668b3241f7b95a2a3b4f1df4e14c12faf14478 Mon Sep 17 00:00:00 2001 From: Julio Estrada Date: Thu, 8 Jan 2026 16:36:41 -0500 Subject: [PATCH 4/8] Adds a "Tools" link next to the category dropdown that scrolls users to the Tools section. Includes tooltip on hover. --- libraries/constants.py | 12 ++++++++++++ templates/libraries/categorized_list.html | 2 +- templates/libraries/grid_list.html | 2 +- .../libraries/includes/library_preferences.html | 8 ++++++-- templates/libraries/vertical_list.html | 2 +- 5 files changed, 21 insertions(+), 5 deletions(-) diff --git a/libraries/constants.py b/libraries/constants.py index ec15fe425..3598995ea 100644 --- a/libraries/constants.py +++ b/libraries/constants.py @@ -370,6 +370,18 @@ RELEASE_REPORT_AUTHORS_PER_PAGE_THRESHOLD = 6 TOOLS = [ + { + "name": "AutoIndex", + "description": "AutoIndex is a tool for taking the grunt work out of indexing a Boostbook/Docbook document (perhaps generated by your Quickbook file mylibrary.qbk, and perhaps using also Doxygen autodoc) that describes C/C++ code.", + "version_specific": False, + "url_path": "https://github.com/boostorg/auto_index", + }, + { + "name": "BoostDep", + "description": "Boostdep is a tool for generating Boost dependency reports. It scans the header or source files of the Boost libraries for #include directives, builds a dependency graph from this information and outputs its findings in plain text or HTML.", + "version_specific": False, + "url_path": "https://github.com/boostorg/boostdep", + }, { "name": "boostlook", "description": "A CSS framework for Boost C++ Library documentation.", diff --git a/templates/libraries/categorized_list.html b/templates/libraries/categorized_list.html index 0ee9f69b4..c778d0efb 100644 --- a/templates/libraries/categorized_list.html +++ b/templates/libraries/categorized_list.html @@ -16,7 +16,7 @@ {# Libraries list #}
{% for result in library_versions_by_category %} -
+
{{ result.category.name }}
{% if result.tools %}

Boost developers, testers, and maintainers have developed various programs to help with the administration of the Boost Libraries. Like everything else about Boost, these tools are available in source form, and are part of the regular Boost distribution.

diff --git a/templates/libraries/grid_list.html b/templates/libraries/grid_list.html index b0593841e..6f2e30d5c 100644 --- a/templates/libraries/grid_list.html +++ b/templates/libraries/grid_list.html @@ -21,7 +21,7 @@ {# end libraries list #} {# Tools section #} -
+

Tools

Boost developers, testers, and maintainers have developed various programs to help with the administration of the Boost Libraries. Like everything else about Boost, these tools are available in source form, and are part of the regular Boost distribution.

diff --git a/templates/libraries/includes/library_preferences.html b/templates/libraries/includes/library_preferences.html index 933d4a87c..d925eb957 100644 --- a/templates/libraries/includes/library_preferences.html +++ b/templates/libraries/includes/library_preferences.html @@ -26,8 +26,6 @@
-
- {# Select a category #}
- {# Tools link #} -
- Tools - Scroll to Boost tools -
{# Select a version #}
{% include "libraries/includes/dev_master_links.html" %} From 7a5861587ec99342ca44d99905ad6ec93146968e Mon Sep 17 00:00:00 2001 From: Julio Estrada Date: Tue, 13 Jan 2026 15:25:22 -0500 Subject: [PATCH 6/8] Remove "Wave" tool entry from the TOOLS constant in constants.py --- libraries/constants.py | 7 ------- 1 file changed, 7 deletions(-) diff --git a/libraries/constants.py b/libraries/constants.py index 3598995ea..244624c75 100644 --- a/libraries/constants.py +++ b/libraries/constants.py @@ -425,11 +425,4 @@ "url_path": "https://www.boost.org/doc/libs/latest/doc/html/quickbook.html", "version_specific": False, }, - { - "name": "Wave", - "slug": "wave", - "description": "A Standards conformant C/C++ preprocessor usable on top of any other compiler. Usable for instance for the debugging of the expansion of macros in your code or as a replacement for your built-in preprocessor.", - "version_specific": True, - "url_path": "libs/wave/index.html", - }, ] From bc57cee97fc816c5bc0111f4259a0a302ed4be54 Mon Sep 17 00:00:00 2001 From: "Julio C. Estrada" Date: Thu, 15 Jan 2026 13:10:21 -0500 Subject: [PATCH 7/8] Update libraries/constants.py Co-authored-by: Greg Kaleka --- libraries/constants.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/libraries/constants.py b/libraries/constants.py index 244624c75..6e3b5a615 100644 --- a/libraries/constants.py +++ b/libraries/constants.py @@ -422,7 +422,7 @@ { "name": "QuickBook", "description": "QuickBook is a WikiWiki style documentation tool geared towards C++ documentation using simple rules and markup for simple formatting tasks. QuickBook generates BoostBook XML.", - "url_path": "https://www.boost.org/doc/libs/latest/doc/html/quickbook.html", + "url_path": "/doc/libs/latest/doc/html/quickbook.html", "version_specific": False, }, ] From 0fa16037744ecdb52f367337b9b7adde9abb6878 Mon Sep 17 00:00:00 2001 From: "Julio C. Estrada" Date: Thu, 15 Jan 2026 13:10:35 -0500 Subject: [PATCH 8/8] Update libraries/utils.py Co-authored-by: Greg Kaleka --- libraries/utils.py | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/libraries/utils.py b/libraries/utils.py index b5861d56d..0ad87d219 100644 --- a/libraries/utils.py +++ b/libraries/utils.py @@ -392,16 +392,14 @@ def get_tools(version=None): - description: str - url: str (generated for version_specific tools if version provided) """ + version_slug = version.stripped_boost_url_slug tools = [] for tool in TOOLS.copy(): tool_dict = tool.copy() url_path = tool_dict.get("url_path", "") if tool_dict.get("version_specific"): if version: - version_slug = version.stripped_boost_url_slug - tool_dict["url"] = ( - f"https://www.boost.org/doc/libs/{version_slug}/{url_path}" - ) + tool_dict["url"] = f"/doc/libs/{version_slug}/{url_path}" else: tool_dict["url"] = "" else: