book-builder 0.1.0

Utilities for building a PreTeXt textbook workflow from mixed open-source inputs (CNXML and PreTeXt)

book-builder

book-builder is a CLI for building a PreTeXt textbook workspace from planning CSVs and open-source source books (CNXML + PreTeXt).

It is designed for a practical production flow:

1. Generate a full source/ + reference/ skeleton from curriculum metadata.
2. Export source TOCs to normalized CSVs.
3. Populate reference/ with adapted content.
4. Run content enrich/audit workflows.

Quick entry (2-minute start)

Install:

pipx install book-builder

From your textbook project root (the folder that contains textbook_info/):

# 1) Generate source + reference structure
book-builder skeleton

# 2) Populate reference content from TOC/metadata
book-builder populate

# 3) Run typical content post-processing
book-builder content

See all commands:

book-builder --help

Project Structure for Users

When users install book-builder and use it, they'll work with this structure:

my-textbook-project/
├── textbook_info/
│   ├── template.ptx
│   ├── Book Structure.csv
│   ├── Open Textbooks.csv
│   ├── Automatic Links.csv
│   └── Learning Outcomes.csv
├── source/
│   ├── content.ptx
│   └── [chapter directories and sec-*.ptx files]
├── reference/
│   ├── content.ptx
│   └── [chapter directories and sec-*.ptx files]
├── reference_tocs/
│   ├── stax-toc.csv
│   ├── orcca-toc.csv
│   └── [other generated toc / id-map CSV files]
├── assets/
│   ├── lesson_plans/
│   └── [images/media copied during processing]
├── adapted-works/
│   └── [upstream CNXML or PreTeXt source repositories]
├── secret/
│   ├── credentials.json
│   ├── google_ids.json
│   └── token.pickle
└── [other project files]

All paths are resolved relative to your current working directory (Path.cwd()), not the package installation folder.

Required input files vs generated files

Required inputs (you provide)

These should exist before running the listed commands.

• textbook_info/template.ptx
  • used by: book-builder skeleton (for source/ section template)
• textbook_info/Book Structure.csv
  • used by: book-builder skeleton, book-builder populate
  • automatically generate through book-builder load-textbook-sheet
• textbook_info/Open Textbooks.csv
  • used by: book-builder populate
  • automatically generate through book-builder load-open-textbooks-sheet
• textbook_info/Automatic Links.csv
  • used by: book-builder add-objectives, book-builder add-resources, book-builder generate-syllabus, book-builder generate-lo, book-builder syllabus-tables, book-builder validate-paths
• textbook_info/Learning Outcomes.csv
  • used by: book-builder generate-lo, book-builder syllabus-tables
  • automatically generate through book-builder load-textbook-sheet

Optional but commonly needed:

• adapted-works/...
  • used by: book-builder stax-toc, book-builder pretext-toc, and then indirectly by populate
• secret/credentials.json (required for Google API auth)
  • used by: book-builder pull-plans, book-builder validate-paths, book-builder audit
• secret/google_ids.json (sheet/folder IDs)
  • used by: book-builder pull-plans, book-builder validate-paths, book-builder audit
  • This should have structure:

      {
          "grade" : 
              {"grade_10":
                  {"textbook_spreadsheet_id": "XXXX",
                  "lesson_plans_folder_id": "XXXX"
                  },
              "grade_11":
                  {"textbook_spreadsheet_id": "XXXX",
                   "lesson_plans_folder_id": "XXXX"
                  }
              },
          "open_textbooks_spreadsheet_id": "XXXX"
      }
  

Generated files/directories (tool creates)

• source/ and reference/ trees
  • generated by: book-builder skeleton
  • includes content.ptx, chapter folders, and section files
  • Important: reference/ is generated by skeleton
• reference_tocs/*.csv
  • generated by: book-builder stax-toc, book-builder pretext-toc
• reference_tocs/*-id-mapping.csv
  • generated by: book-builder pretext-toc (mapping output)
• reference_tocs/stax-toc.enriched.csv
  • generated by: book-builder populate (default CNXML/auto flow)
• assets/lesson_plans/*
  • generated/downloaded by: book-builder pull-plans
• textbook_info/orphaned_ptx, textbook_info/orphaned.ptx
  • generated by: book-builder audit-questions
• source/syllabus-alignment.ptx, source/lo-coverage-table.ptx
  • generated by: book-builder generate-syllabus, book-builder generate-lo, or book-builder syllabus-tables
• secret/token.pickle
  • generated on first successful Google OAuth flow

Command map

Core workflow

• book-builder skeleton
  • create empty source/ and reference/ structures from Book Structure.csv
• book-builder populate
  • match rows to TOC entries and inject adapted content into reference/
• book-builder content
  • run common post-processing sequence:
    • add-objectives
    • add-resources
    • namespace
    • generate-syllabus
    • generate-lo

TOC generation

• book-builder stax-toc <resource_folder> <collection_name>
  • export CNXML collection structure to reference_tocs/
• book-builder pretext-toc <root>
  • export PreTeXt include tree to reference_tocs/

Content helpers

• book-builder add-objectives
• book-builder add-resources
• book-builder namespace
• book-builder add-labels
• book-builder generate-syllabus
• book-builder generate-lo
• book-builder syllabus-tables

Audits and Google sync

• book-builder pull-plans
• book-builder validate-paths
• book-builder audit-pdfs
• book-builder audit-questions
• book-builder audit (runs pull + validate + pdf audit + question audit)

Typical end-to-end workflow

# 0) Inspect command options
book-builder --help

# 1) Build source/reference scaffold from curriculum plan
book-builder skeleton

# 2) Build TOCs from source repositories (examples)
book-builder stax-toc adapted-works/PREALG prealgebra-2e
book-builder pretext-toc adapted-works/ORCCA/src/orcca.ptx --resource-name ORCCA

# 3) Populate reference content
book-builder populate --source-format auto

# 4) Add objectives/resources/namespace/syllabus tables
book-builder content

# 5) Optional audits
book-builder audit-questions
book-builder audit-pdfs

Useful populate flags while testing:

• --limit N to process only first N matching rows
• --dry-run to run matching without writes
• --no-copy-images to skip image copy

Installation

From PyPI (recommended)

pipx install book-builder

Development install

git clone https://github.com/B28LH/book-builder.git
cd book-builder
pip install -e .[dev]

Requirements:

• Python 3.12+

Development

Common Make targets:

make run-checks   # isort, black, ruff, mypy, pytest
make docs         # local Sphinx autobuild
make build        # package build artifacts

Documentation lives under docs/source.

Troubleshooting

• If commands cannot find textbook_info/..., make sure you are running from your project root.
• If Google commands fail auth, confirm both secret/credentials.json and secret/google_ids.json exist.
• secret/token.pickle is created automatically after OAuth; deleting it forces re-auth.
• If populate has poor matches, verify Book Structure.csv, Open Textbooks.csv, and TOC CSVs are aligned.

License

This project is licensed under the terms in LICENSE.