order PDF sections using the same metadata as the site

Author: josh-heyer

.github/workflows/deploy-develop.yml

@@ -48,6 +48,8 @@ jobs:
         run: |
           curl -L https://github.com/wkhtmltopdf/packaging/releases/download/0.12.6-1/wkhtmltox_0.12.6-1.focal_amd64.deb > wkhtmltopdf.deb
           sudo apt-get install ./wkhtmltopdf.deb
+      - name: Install Python dependencies
+        run: pip install -r requirements-ci.txt
 
       - name: Build all pdfs
         run: npm run pdf:build-all-ci

.github/workflows/deploy-main.yml

@@ -50,6 +50,8 @@ jobs:
         run: |
           curl -L https://github.com/wkhtmltopdf/packaging/releases/download/0.12.6-1/wkhtmltox_0.12.6-1.focal_amd64.deb > wkhtmltopdf.deb
           sudo apt-get install ./wkhtmltopdf.deb
+      - name: Install Python dependencies
+        run: pip install -r requirements-ci.txt
 
       - name: Build all pdfs
         run: npm run pdf:build-all-ci

docker/images/Dockerfile.pdf-builder

@@ -7,6 +7,7 @@ ARG WKHTML_TO_PDF_DEB=wkhtmltox_${WKHTML_TO_PDF_VERSION}-1.focal_amd64.deb
 
 RUN apt-get update && apt-get install --no-install-recommends -y \
   python3 \
+  python3-pip \
   wget \
   && apt-get clean \
   && rm -rf /var/lib/apt/lists/*
@@ -25,3 +26,7 @@ RUN wget --quiet --no-check-certificate -P /tmp https://github.com/wkhtmltopdf/p
   && apt-get clean \
   && rm -rf /var/lib/apt/lists/* \
   && rm -rf /tmp/*
+
+# Install python dependencies
+COPY requirements-ci.txt .
+RUN pip install --no-cache-dir -r requirements-ci.txt

requirements-ci.in

@@ -0,0 +1,2 @@
+python-frontmatter
+

requirements-ci.txt

@@ -0,0 +1,10 @@
+#
+# This file is autogenerated by pip-compile with python 3.10
+# To update, run:
+#
+#    pip-compile requirements-ci.in
+#
+python-frontmatter==1.0.0
+    # via -r requirements-ci.in
+pyyaml==6.0
+    # via python-frontmatter

requirements.in

@@ -1,3 +1,4 @@
 pdftotext
 pip-tools
 pytest
+python-frontmatter

requirements.txt

@@ -1,5 +1,5 @@
 #
-# This file is autogenerated by pip-compile
+# This file is autogenerated by pip-compile with python 3.10
 # To update, run:
 #
 #    pip-compile
@@ -26,6 +26,10 @@ pyparsing==2.4.7
     # via packaging
 pytest==6.2.4
     # via -r requirements.in
+python-frontmatter==1.0.0
+    # via -r requirements.in
+pyyaml==6.0
+    # via python-frontmatter
 toml==0.10.2
     # via pytest
 tomli==1.0.4

scripts/pdf/__tests__/combine_mdx/expected.mdx

@@ -8,9 +8,9 @@
 
 ### Heading 2
 
-### Heading 3
+#### Heading 3
 
-#### Heading 4
+##### Heading 4
 
 
 ---
@@ -23,7 +23,7 @@
 
 ### Heading 2
 
-### Heading 3
+#### Heading 3
 
-#### Heading 4
+##### Heading 4
 

scripts/pdf/__tests__/list_files/test_cases/navigation_frontmatter/1.mdx

@@ -0,0 +1,5 @@
+---
+title: 'Title'
+---
+
+# Title

scripts/pdf/__tests__/list_files/test_cases/navigation_frontmatter/2.1/2.1.mdx

@@ -0,0 +1,5 @@
+---
+title: 'Title'
+---
+
+# Title

scripts/pdf/__tests__/list_files/test_cases/navigation_frontmatter/2.1/index.mdx

@@ -0,0 +1,3 @@
+---
+title: 'Title'
+---

scripts/pdf/__tests__/list_files/test_cases/navigation_frontmatter/2.mdx

@@ -0,0 +1,5 @@
+---
+title: 'Title'
+---
+
+# Title

scripts/pdf/__tests__/list_files/test_cases/navigation_frontmatter/expected.py

@@ -0,0 +1,10 @@
+from pathlib import Path
+
+from .....generate_pdf import TocItem
+
+expected = [
+    TocItem(filename=Path(__file__).parent / "index.mdx", chapter=[1]),
+    TocItem(filename=Path(__file__).parent / "2.mdx", chapter=[2]),
+    TocItem(filename=Path(__file__).parent / "2.1/2.1.mdx", chapter=[3]),
+    TocItem(filename=Path(__file__).parent / "1.mdx", chapter=[4]),
+]

scripts/pdf/__tests__/list_files/test_cases/navigation_frontmatter/index.mdx

@@ -0,0 +1,9 @@
+---
+title: 'Title'
+navigation:
+  - "2"
+  - "2.1"
+  - "1"
+---
+
+# Title

scripts/pdf/generate_pdf.py

@@ -7,6 +7,7 @@
 from pathlib import Path
 from subprocess import run
 from typing import List
+import frontmatter
 
 BASE_DIR = Path(__file__).resolve().parent
 
@@ -121,8 +122,8 @@ def main(args):
 
 def setup(args):
     doc_path = args.doc_path
-    product = doc_path.parts[2]
-    version = doc_path.parts[3]
+    product = doc_path.parts[-2] if len(doc_path.parts) >= 4 else doc_path.parts[-1] 
+    version = doc_path.parts[-1] if len(doc_path.parts) >= 4 else ''
 
     _file_prefix = f"{product}_v{version}_documentation"
 
@@ -140,8 +141,9 @@ def setup(args):
 def list_files(doc_path, chapter=None, is_root_dir=True):
     chapter = [1] if chapter is None else chapter
     all_files = []
+    nav_order = load_nav_index(doc_path)
     directory_contents = sorted(
-        filter(filter_path, doc_path.iterdir()), key=put_index_first
+        filter(filter_path, doc_path.iterdir()), key=lambda file: put_index_first(file, nav_order)
     )
 
     for i, entry in enumerate(directory_contents):
@@ -226,10 +228,20 @@ def parse_mdx(mdx_file):
     front_matter, _, content = mdx_file.read_text().partition("---")[2].partition("---")
     return front_matter.strip(), content.strip()
 
-
-def put_index_first(path):
-    filename = str(path)
-    return filename.replace("index.mdx", "00_index.mdx")
+def load_nav_index(path):
+    try:
+        index = frontmatter.load(path / "index.mdx")["navigation"]
+        return index
+    except (FileNotFoundError, KeyError):
+        return None
+
+def put_index_first(path, nav_order):
+    filename = path.name if path.suffix != ".mdx" else path.stem
+    nav_order = nav_order or [filename]
+    indice = 0
+    if path.name != "index.mdx":
+        indice = nav_order.index(filename)+1 if filename in nav_order else len(nav_order)
+    return f'{indice:03d}_{filename}'
 
 
 def get_title(doc_path):