Added generator logic.

pyproject.toml

@@ -11,6 +11,7 @@ dependencies = [
     "requests==2.32.3",
     "pydantic==2.8.2",
     "zimscraperlib==3.4.0",
+    "Jinja2==3.1.3",
 ]
 dynamic = ["authors", "classifiers", "keywords", "license", "version", "urls"]
 
@@ -23,7 +24,7 @@ lint = [
   "ruff==0.5.1",
 ]
 check = [
-  "pyright==1.1.370",
+  "pyright==1.1.374",
 ]
 test = [
   "pytest==8.2.2",

src/devdocs2zim/assets/COPYRIGHT

@@ -0,0 +1,13 @@
+Copyright 2013-2024 Thibaut Courouble and other contributors
+
+  This Source Code Form is subject to the terms of the Mozilla Public
+  License, v. 2.0. If a copy of the MPL was not distributed with this
+  file, You can obtain one at http://mozilla.org/MPL/2.0/.
+
+Please do not use the name DevDocs to endorse or promote products
+derived from this software without the maintainers' permission, except
+as may be necessary to comply with the notice/attribution requirements.
+
+We also wish that any documentation file generated using this software
+be attributed to DevDocs. Let's be fair to all contributors by giving
+credit where credit's due. Thanks.

src/devdocs2zim/assets/README.md

@@ -0,0 +1,7 @@
+These files are copied from DevDocs:
+
+    https://github.com/freeCodeCamp/devdocs
+
+devdocs_48.png is adapted from:
+
+     https://github.com/freeCodeCamp/devdocs/blob/0dd0ad813f81d3c8e3d040095992e61b7398be96/public/images/icon-64.png

src/devdocs2zim/client.py

@@ -1,10 +1,23 @@
+import re
+from collections import defaultdict
+from enum import Enum
+
 import requests
 from pydantic import BaseModel, TypeAdapter
 
 from devdocs2zim.constants import logger
 
 HTTP_TIMEOUT_SECONDS = 15
 
+# These regular expressions are extracted from the DevDocs frontend.
+# The expression definitions haven't changed in ~8 years as of 2024-07-28:
+# https://github.com/freeCodeCamp/devdocs/blob/e28f81d3218bdbad7eac0540c58c11c7fe1d33d3/assets/javascripts/collections/types.js#L3
+BEFORE_CONTENT_PATTERN = re.compile(
+    r"(^|\()(guides?|tutorials?|reference|book|getting\ started|manual|examples)($|[\):])",  # noqa: E501
+    re.IGNORECASE,
+)
+AFTER_CONTENT_PATTERN = re.compile(r"appendix", re.IGNORECASE)
+
 
 class DevdocsMetadataLinks(BaseModel):
     """Project links for a specific documentation set."""
@@ -74,14 +87,24 @@ class DevdocsIndexEntry(BaseModel):
     path: str
 
     # Name of the type (section) the entry is located under.
-    type: str
+    type: str | None
 
     @property
     def path_without_fragment(self) -> str:
         """Key in db.json for the file's contents."""
         return self.path.split("#")[0]
 
 
+class SortPrecedence(Enum):
+    """Represents where to place section in the navbar."""
+
+    # NOTE: Definition order must match display order.
+
+    BEFORE_CONTENT = 0
+    CONTENT = 1
+    AFTER_CONTENT = 2
+
+
 class DevdocsIndexType(BaseModel):
     """A section header for documentation."""
 
@@ -94,6 +117,37 @@ class DevdocsIndexType(BaseModel):
     # Section slug. This appears to be unused.
     slug: str
 
+    def sort_precedence(self) -> SortPrecedence:
+        """Determines where this section should be displayed in the navigation."""
+        if BEFORE_CONTENT_PATTERN.match(self.name):
+            return SortPrecedence.BEFORE_CONTENT
+
+        if AFTER_CONTENT_PATTERN.match(self.name):
+            return SortPrecedence.AFTER_CONTENT
+
+        return SortPrecedence.CONTENT
+
+
+class NavigationSection:
+    """Represents a single section of a devdocs navigation tree."""
+
+    def __init__(self, section: DevdocsIndexType, links: list[DevdocsIndexEntry]):
+        """Initializes NavigationSection.
+
+        Parameters:
+            section: Heading information for the group of links.
+            links: Links to display in the section.
+        """
+        self.name = section.name
+        self.count = section.count
+        self.links = links
+
+        self._contained_pages = {link.path_without_fragment for link in links}
+
+    def contains_page(self, page_path: str) -> bool:
+        """Returns whether this section contains the given page."""
+        return page_path in self._contained_pages
+
 
 class DevdocsIndex(BaseModel):
     """Represents entries in the /<slug>/index.json file for each resource."""
@@ -102,10 +156,36 @@ class DevdocsIndex(BaseModel):
     entries: list[DevdocsIndexEntry]
 
     # List of "types" or section headings.
-    # These are displayed mostly in order, except regular expressions are used to sort:
-    # https://github.com/freeCodeCamp/devdocs/blob/e28f81d3218bdbad7eac0540c58c11c7fe1d33d3/assets/javascripts/collections/types.js#L3
+    # These are displayed in the order they're found grouped by sort_precedence.
     types: list[DevdocsIndexType]
 
+    def build_navigation(self) -> list[NavigationSection]:
+        """Builds a navigation hierarchy that's soreted correctly for rendering."""
+
+        sections_by_precedence: dict[SortPrecedence, list[DevdocsIndexType]] = (
+            defaultdict(list)
+        )
+        for section in self.types:
+            sections_by_precedence[section.sort_precedence()].append(section)
+
+        links_by_section_name: dict[str, list[DevdocsIndexEntry]] = defaultdict(list)
+        for entry in self.entries:
+            if entry.type is None:
+                continue
+            links_by_section_name[entry.type].append(entry)
+
+        output: list[NavigationSection] = []
+        for precedence in SortPrecedence:
+            for section in sections_by_precedence[precedence]:
+                output.append(
+                    NavigationSection(
+                        section=section,
+                        links=links_by_section_name[section.name],
+                    )
+                )
+
+        return output
+
 
 class DevdocsClient:
     """Utility functions to read data from devdocs."""