Docs fixes and fix bug in library import (#1788)

Author: GregKaleka

config/settings.py

@@ -562,3 +562,5 @@
         "ROOT_TAG_EXTRA_ATTRS": "hx-preserve",
     }
     MIDDLEWARE.append("debug_toolbar.middleware.DebugToolbarMiddleware")
+
+BOOST_BRANCHES = ["master", "develop"]

core/views.py

@@ -39,6 +39,7 @@
     convert_name_to_id,
     modernize_preprocessor_docs,
     slightly_modernize_legacy_library_doc_page,
+    remove_library_boostlook,
 )
 from .markdown import process_md
 from .models import RenderedContent
@@ -497,6 +498,13 @@ def normalize_boost_doc_path(content_path: str) -> str:
     "libs/variant2",
 ]
 
+FULLY_MODERNIZED_LIB_VERSIONS = [
+    # FIXME: we should have a way to opt-in via a flag on the library/lib-version.
+    #  Hard-coding these here as a quick fix for now.
+    "boost_1_87_0/libs/charconv",
+    "boost_1_88_0/libs/charconv",
+]
+
 
 class DocLibsTemplateView(BaseStaticContentTemplateView):
     def get_from_s3(self, content_path):
@@ -506,6 +514,12 @@ def get_from_s3(self, content_path):
     def process_content(self, content):
         """Replace page header with the local one."""
 
+        if any(
+            lib_slug in self.request.path for lib_slug in FULLY_MODERNIZED_LIB_VERSIONS
+        ):
+            # Return a fully modernized version in an iframe
+            return self._fully_modernize_content(content)
+
         if any(lib_slug in self.request.path for lib_slug in NO_PROCESS_LIBS):
             # Just render raw HTML for some pages
             return content
@@ -527,6 +541,69 @@ def process_content(self, content):
 
         return render_to_string("original_docs.html", context, request=self.request)
 
+    def _fully_modernize_content(self, content):
+        """For libraries that have opted in to boostlook modernization"""
+        content_type = self.content_dict.get("content_type")
+        source_content_type = self.content_dict.get("source_content_type")
+        if (
+            source_content_type is None
+            and SourceDocType.ANTORA.value in self.request.path
+        ):
+            # hacky, but solves an edge case
+            source_content_type = SourceDocType.ANTORA
+        # Is the request coming from an iframe? If so, let's disable the modernization.
+        sec_fetch_destination = self.request.headers.get("Sec-Fetch-Dest", "")
+        is_iframe_destination = sec_fetch_destination in ["iframe", "frame"]
+
+        modernize = self.request.GET.get("modernize", "med").lower()
+
+        if (
+            ("text/html" or "text/html; charset=utf-8") not in content_type
+            or modernize not in ("max", "med", "min")
+            or is_iframe_destination
+        ):
+            # eventually check for more things, for example ensure this HTML
+            # was not generate from Antora builders.
+            return content
+
+        context = {"disable_theme_switcher": False}
+        insert_body = modernize == "max"
+        head_selector = (
+            "head"
+            if modernize in ("max", "med")
+            else {"data-modernizer": "boost-legacy-docs-extra-head"}
+        )
+
+        context["hide_footer"] = True
+        if source_content_type == SourceDocType.ASCIIDOC:
+            extracted_content = content.decode(chardet.detect(content)["encoding"])
+            soup = BeautifulSoup(extracted_content, "html.parser")
+            soup = convert_name_to_id(soup)
+            soup = remove_library_boostlook(soup)
+            soup.find("head").append(
+                soup.new_tag("script", src=f"{settings.STATIC_URL}js/theme_handling.js")
+            )
+            context["content"] = soup.prettify()
+        else:
+            # Potentially pass version if needed for HTML modification.
+            # We disable plausible to prevent redundant 'about:srcdoc' tracking,
+            # tracking is covered by docsiframe.html
+            base_html = render_to_string(
+                "docs_libs_placeholder.html",
+                {**context, **{"disable_plausible": True}},
+                request=self.request,
+            )
+            context["content"] = modernize_legacy_page(
+                content,
+                base_html,
+                insert_body=insert_body,
+                head_selector=head_selector,
+                original_docs_type=source_content_type,
+                show_footer=False,
+                show_navbar=False,
+            )
+        return render_to_string("docsiframe.html", context, request=self.request)
+
 
 class UserGuideTemplateView(BaseStaticContentTemplateView):
     def get_from_s3(self, content_path):

libraries/constants.py

@@ -22,7 +22,7 @@
     generate_library_docs_url_utility_anchor,
 )
 
-# Mapping for exeptions to loading URLs for older docs.
+# Mapping for exceptions to loading URLs for older docs.
 # key: Taken from Library.slug
 # value: List of dictionaries with instructions for how to format docs URLs for
 # those library-versions

libraries/management/commands/import_library_versions.py

@@ -42,7 +42,10 @@ def command(min_release: str, release: str, token: str):
         )
 
     for version in versions.order_by("-name"):
+        version_type = "branch" if version.slug in settings.BOOST_BRANCHES else "tag"
         click.secho(f"Saving libraries for version {version.name}", fg="green")
-        import_library_versions.delay(version.name, token=token)
+        import_library_versions.delay(
+            version.name, token=token, version_type=version_type
+        )
 
     click.secho("Finished saving library-version relationships.", fg="green")

templates/docsiframe.html

@@ -1,5 +1,4 @@
 {% extends "base.html" %}
-{% block main_content_wrapper %}<div class="md:px-3 mx-auto transition-all">{% endblock %}
 {% block content %}
     <iframe
         {% if iframe_url %}

templates/libraries/_library_categorized_list_item.html

@@ -13,10 +13,8 @@
           {% if library_version.cpp_standard_minimum and library_version.cpp_standard_minimum != 'None' %}{{ library_version.cpp_standard_minimum }}{% else %}03{% endif %}
     </span>
   </td>
-  <td class="py-3 pr-2 align-top">
-    <a class="text-sky-600 dark:text-sky-300 text-base" href="{{ library_version.documentation_url }}" title="Documentation">
-      <i class="fa fa-book icon-link"></i>
-    </a>
+  <td class="align-top">
+    {% include "libraries/includes/_documentation_link_icon.html" %}
   </td>
   <td class="hidden md:block py-2 pl-3 align-top">{{ library_version.description|default:"No description provide for this version." }}</td>
 </tr>

templates/libraries/_library_grid_list_item.html

@@ -7,9 +7,7 @@
     <h3 class="pb-2 text-xl md:text-2xl capitalize border-b border-gray-700">
     <div class="flex justify-between">
       <a class="link-header" href="{% url 'library-detail' library_slug=library_version.library.slug version_slug=version_str %}">{{ library_version.library.name }}</a>
-      <a class="text-sky-600 dark:text-sky-300 text-base" href="{{ library_version.documentation_url }}" title="Documentation">
-        <i class="fa fa-book icon-link"></i>
-      </a>
+      {% include "libraries/includes/_documentation_link_icon.html" %}
     </div>
       {% for author in library.authors.all %}
         {% if author.image %}

templates/libraries/_library_vertical_list_item.html

@@ -12,10 +12,8 @@
           {% if library_version.cpp_standard_minimum and library_version.cpp_standard_minimum != 'None' %}{{ library_version.cpp_standard_minimum }}{% else %}03{% endif %}
     </span>
   </td>
-  <td class="py-3 pr-2 align-top">
-    <a class="text-sky-600 dark:text-sky-300 text-base" href="{{ library_version.documentation_url }}" title="Documentation">
-      <i class="fa fa-book icon-link"></i>
-    </a>
+  <td class="align-top">
+    {% include "libraries/includes/_documentation_link_icon.html" %}
   </td>
   <td class="hidden md:block py-2 pl-3 align-top">{{ library_version.description|default:"No description provide for this version." }}</td>
 </tr>

templates/libraries/includes/_documentation_link_icon.html

@@ -0,0 +1,3 @@
+<a class="text-sky-600 dark:text-sky-300 hover:text-orange dark:hover:text-orange text-base block py-3 pr-2" href="{{ library_version.documentation_url }}" title="Documentation">
+  <i class="fa fa-book icon-link"></i>
+</a>

templates/original_docs.html

@@ -9,12 +9,6 @@
     <script src="{% static 'js/boost-gecko/main.eb9cabc5.js' %}" defer></script>
   </head>
   <style>
-    /*
-    Copyright 2005-2006 Redshift Software, Inc.
-    Distributed under the Boost Software License, Version 1.0.
-    (See accompanying file LICENSE_1_0.txt or https://www.boost.org/LICENSE_1_0.txt)
-    */
-
     body {
       margin-top: 0;
     }
@@ -41,6 +35,10 @@
       margin: 18px 0px 0px 24px;
     }
 
+
+    #injected-header * {
+      color: #000;
+    }
     /* Links in the header. */
     #boost-common-heading-doc .heading-quote a,
     #heading .heading-quote a {
@@ -220,11 +218,15 @@
   </style>
 
   {% if no_wrapper %}
+    <div id="injected-header">
     {% include "includes/_legacy_docs_header.html" %}
+    </div>
     {{ content|safe }}
   {% else %}
     <body style="margin: 0; padding: 0; max-width: unset;">
+      <div id="injected-header">
       {% include "includes/_legacy_docs_header.html" %}
+      </div>
       <div style="margin: 1em;">
         {{ content|safe }}
       </div>

versions/tasks.py

@@ -8,6 +8,7 @@
 from django.conf import settings
 from django.core.management import call_command
 from fastcore.xtras import obj2dict
+
 from core.githubhelper import GithubAPIClient, GithubDataParser
 from libraries.constants import SKIP_LIBRARY_VERSIONS
 from libraries.github import LibraryUpdater
@@ -160,10 +161,9 @@ def import_version(
 @app.task
 def import_development_versions():
     """Imports the `master` and `develop` branches as Versions"""
-    branches = ["master", "develop"]
     base_url = "https://github.com/boostorg/boost/tree/"
 
-    for branch in branches:
+    for branch in settings.BOOST_BRANCHES:
         import_version.delay(
             branch,
             branch,