Skip to content

Add tools section to Boost library views and templates #2049

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.

Sign up for GitHub

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

Open
julioest wants to merge 8 commits into
base: develop
Choose a base branch
from
Open

Add tools section to Boost library views and templates #2049

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
f8a3255
WIP: Add tools section to Boost library views and templates
julioest Dec 16, 2025
ec7e44c
Enhance tools functionality in Boost library
julioest Dec 17, 2025
62db6a1
Refactor tool list item templates for improved URL handling
julioest Dec 17, 2025
85668b3
Adds a "Tools" link next to the category dropdown that scrolls users …
julioest Jan 8, 2026
e3453a4
Remove "Tools" link and associated tooltip from library preferences t…
julioest Jan 12, 2026
7a58615
Remove "Wave" tool entry from the TOOLS constant in constants.py
julioest Jan 13, 2026
bc57cee
Update libraries/constants.py
julioest Jan 15, 2026
0fa1603
Update libraries/utils.py
julioest Jan 15, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
57 changes: 57 additions & 0 deletions libraries/constants.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -369,3 +369,60 @@
DOCKER_CONTAINER_URL_WEB = "http://web:8000"

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.",
"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.",
"version_specific": True,
"url_path": "tools/build/doc/html/index.html",
Copy link
Collaborator

@gregjkal gregjkal Jan 14, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Have you tested these urls? I would think they should be root-relative, i.e. have a leading slash.

Suggested change
"url_path": "tools/build/doc/html/index.html",
"url_path": "/tools/build/doc/html/index.html",

},
{
"name": "Regression",
"description": "The Boost regression testing system reporting sources.",
"url_path": "https://www.boost.org/doc/contributor-guide/testing/regression-tests.html",
"version_specific": False,
},
{
"name": "Inspect",
"description": "The inspection tool used to detect errors in the Boost directory hierarchy.",
"version_specific": True,
"url_path": "tools/inspect/index.html",
},
{
"name": "BoostBook",
"description": "A Boost documentation system, based on DocBook and the Extensible Stylesheet Language (XSL), used by some Boost libraries.",
"version_specific": True,
"url_path": "tools/boostbook/index.html",
},
{
"name": "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).",
"version_specific": True,
"url_path": "tools/bcp/",
},
{
"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": "/doc/libs/latest/doc/html/quickbook.html",
"version_specific": False,
},
]
37 changes: 37 additions & 0 deletions libraries/utils.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -370,3 +371,39 @@ 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(version=None):
"""
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.

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
- 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:
tool_dict["url"] = f"/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())
19 changes: 19 additions & 0 deletions libraries/views.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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(version=context.get("selected_version"))
# todo: add tests for sort order
if self.kwargs.get("category_slug"):
context["category"] = Category.objects.get(
Expand Down Expand Up @@ -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(version=version)
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


Expand Down
23 changes: 23 additions & 0 deletions templates/libraries/_tool_categorized_list_item.html
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,23 @@
{% if tool.url %}
<tr class="border-0 md:border border-gray-200/10 border-dotted md:border-t-0 md:border-r-0 md:border-l-0 md:border-b-1 hover:bg-gray-100 dark:hover:bg-gray-700 transition-all duration-200 ease-in-out cursor-pointer" onclick="window.open('{{ tool.url }}', '_blank', 'noopener,noreferrer')">
{% else %}
<tr class="border-0 md:border border-gray-200/10 border-dotted md:border-t-0 md:border-r-0 md:border-l-0 md:border-b-1 hover:bg-gray-100 dark:hover:bg-gray-700 transition-all duration-200 ease-in-out">
{% endif %}
<td class="py-2 align-top md:w-1/5">
<span class="mr-1 font-bold capitalize text-sky-600 dark:text-sky-300">{{ tool.name }}</span>
</td>

<td class="w-12 align-top pt-2.5 pr-2">
{# Empty cell for alignment with library rows #}
</td>
<td class="w-8 pt-2 px-2 text-center align-top">
{# Empty cell for alignment with library rows #}
</td>
<td class="w-8 text-center align-top">
{# Empty cell for alignment with library rows #}
</td>
<td class="hidden md:block py-2 pl-3 align-top" style="min-height: 3rem;">{{ tool.description }}</td>
</tr>
<tr class="block md:hidden">
<td>{{ tool.description }}</td>
</tr>
18 changes: 18 additions & 0 deletions templates/libraries/_tool_grid_list_item.html
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,18 @@
{% load static %}

{% if tool.url %}
<a href="{{ tool.url }}" target="_blank" rel="noopener noreferrer" class="block h-full">
{% endif %}
<div class="relative flex flex-col h-full p-3 bg-white md:rounded-lg md:shadow-lg md:p-5 dark:bg-charcoal hover:bg-gray-100 dark:hover:bg-gray-700 transition-all duration-200 ease-in-out {% if tool.url %}cursor-pointer{% endif %}">
<div class="">
<h3 class="pb-2 text-xl md:text-2xl capitalize border-b border-gray-700">
<span class="link-header">{{ tool.name }}</span>
</h3>
</div>
<div class="mb-3 pb-3 flex-grow">
<p class="mb-3 text-gray-700 dark:text-gray-300">{{ tool.description }}</p>
</div>
</div>
{% if tool.url %}
</a>
{% endif %}
22 changes: 22 additions & 0 deletions templates/libraries/_tool_vertical_list_item.html
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,22 @@
{% if tool.url %}
<tr class="border-0 md:border border-gray-200/10 border-dotted md:border-t-0 md:border-r-0 md:border-l-0 md:border-b-1 hover:bg-gray-100 dark:hover:bg-gray-700 transition-all duration-300 ease-in-out cursor-pointer" onclick="window.open('{{ tool.url }}', '_blank', 'noopener,noreferrer')">
{% else %}
<tr class="border-0 md:border border-gray-200/10 border-dotted md:border-t-0 md:border-r-0 md:border-l-0 md:border-b-1 hover:bg-gray-100 dark:hover:bg-gray-700 transition-all duration-300 ease-in-out">
{% endif %}
<td class="align-top md:w-1/5 pt-3">
<span class="mr-1 pl-1 font-bold capitalize text-sky-600 dark:text-sky-300">{{ tool.name }}</span>
</td>
<td class="w-12 align-top pt-3 pr-2">
{# Empty cell for alignment with library rows #}
</td>
<td class="w-8 text-center align-top pt-3">
{# Empty cell for alignment with library rows #}
</td>
<td class="w-8 align-top">
{# Empty cell for alignment with library rows #}
</td>
<td class="align-top hidden md:block mt-2 pl-3 md:items-center" style="min-height: 3rem;">{{ tool.description }}</td>
</tr>
<tr class="block md:hidden pl-1 align-top">
<td>{{ tool.description }}</td>
</tr>
16 changes: 13 additions & 3 deletions templates/libraries/categorized_list.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,15 +16,25 @@
{# Libraries list #}
<div class="space-y-3">
{% for result in library_versions_by_category %}
<div class="relative content-between p-3 w-full bg-white md:rounded-lg md:shadow-lg md:p-5 dark:bg-charcoal">
<h5 class="mb-2 pb-2 text-xl md:text-2xl leading-tight text-orange border-b border-gray-300 dark:border-slate">{{ result.category }}</h5>
<div {% if result.category.slug == "tools" %}id="tools"{% endif %} class="relative content-between p-3 w-full bg-white md:rounded-lg md:shadow-lg md:p-5 dark:bg-charcoal">
<h5 class="mb-2 pb-2 text-xl md:text-2xl leading-tight text-orange border-b border-gray-300 dark:border-slate">{{ result.category.name }}</h5>
{% if result.tools %}
<p class="text-gray-600 dark:text-gray-400 mb-4 mt-2 text-sm">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.</p>
{% endif %}
<table class="table-auto w-full">
<tbody>
{% for library_version in result.library_version_list %}
{% include "libraries/_library_categorized_list_item.html" %}
{% empty %}
<p class="text-gray-600 dark:text-gray-400">No libraries in this category yet.</p>
{% if not result.tools %}
<p class="text-gray-600 dark:text-gray-400">No libraries in this category yet.</p>
{% endif %}
{% endfor %}
{% if result.tools %}
{% for tool in result.tools %}
{% include "libraries/_tool_categorized_list_item.html" %}
{% endfor %}
{% endif %}
</tbody>
</table>
</div>
Expand Down
12 changes: 12 additions & 0 deletions templates/libraries/grid_list.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,18 @@
</div>
{# end libraries list #}

{# Tools section #}
<div id="tools" class="mt-8 mb-5">
<h2 class="text-2xl md:text-3xl font-bold text-orange mb-2">Tools</h2>
<p class="text-gray-600 dark:text-gray-400 mb-4">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.</p>
<div class="grid grid-cols-1 gap-4 md:grid-cols-2 lg:grid-cols-3">
{% for tool in tools %}
{% include "libraries/_tool_grid_list_item.html" %}
{% endfor %}
</div>
</div>
{# end tools section #}

{% if page_obj.paginator %}
{# pagination #}
<div class="space-x-3 text-center">
Expand Down
3 changes: 1 addition & 2 deletions templates/libraries/includes/library_preferences.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,8 +26,6 @@
</div>
</div>

<div></div>

{# Select a category #}
<div>
<select
Expand All @@ -43,6 +41,7 @@
{% endfor %}
</select>
</div>

{# Select a version #}
<div class="flex flex-row lib_pref grow justify-end">
{% include "libraries/includes/dev_master_links.html" %}
Expand Down
14 changes: 14 additions & 0 deletions templates/libraries/vertical_list.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,6 +28,20 @@ <h5 class="pb-2 text-xl md:text-2xl leading-tight text-orange border-b border-gr
</div>
{# end libraries list #}

{# Tools section #}
<div id="tools" class="relative content-between p-3 w-full bg-white md:rounded-lg md:shadow-lg md:p-5 dark:bg-charcoal mt-3">
<h5 class="pb-2 text-xl md:text-2xl leading-tight text-orange border-b border-gray-300 dark:border-slate">Tools</h5>
<p class="text-gray-600 dark:text-gray-400 mb-4 mt-2 text-sm">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.</p>
<table class="table-auto w-full">
<tbody>
{% for tool in tools %}
{% include "libraries/_tool_vertical_list_item.html" %}
{% endfor %}
</tbody>
</table>
</div>
{# end tools section #}

{% if page_obj.paginator %}
{# Pagination #}
<div class="space-x-3 text-center">
Expand Down
Loading