Metadata-Version: 2.4
Name: book-builder
Version: 0.1.0
Summary: Utilities for building a PreTeXt textbook workflow from mixed open-source inputs (CNXML and PreTeXt)
Author-email: Ben Lloyd-Hurwitz <benlloydhurwitz@gmail.com>
License: Copyright © 2026 Benjamin Lloyd-Hurwitz
        
        Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
Project-URL: Homepage, https://github.com/B28LH/book-builder
Project-URL: Repository, https://github.com/B28LH/book-builder
Project-URL: Changelog, https://github.com/B28LH/book-builder/blob/main/CHANGELOG.md
Keywords: pretext,textbook,cnxml,publishing,education
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Education
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: google-api-python-client>=2.80.0
Requires-Dist: google-auth>=2.20.0
Requires-Dist: google-auth-oauthlib>=1.0.0
Requires-Dist: lxml>=4.9.0
Requires-Dist: pandas>=2.0.0
Requires-Dist: pypdf>=3.0.0
Requires-Dist: python-slugify>=8.0.0
Requires-Dist: tqdm>=4.65.0
Provides-Extra: dev
Requires-Dist: ruff; extra == "dev"
Requires-Dist: mypy<2.0,>=1.0; extra == "dev"
Requires-Dist: black<26.0,>=23.0; extra == "dev"
Requires-Dist: isort<5.14,>=5.12; extra == "dev"
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-sphinx; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: twine>=1.11.0; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: setuptools; extra == "dev"
Requires-Dist: wheel; extra == "dev"
Requires-Dist: Sphinx<9.0,>=6.0; extra == "dev"
Requires-Dist: furo==2024.8.6; extra == "dev"
Requires-Dist: myst-parser>=1.0; extra == "dev"
Requires-Dist: sphinx-copybutton; extra == "dev"
Requires-Dist: sphinx-autobuild; extra == "dev"
Requires-Dist: sphinx-autodoc-typehints==1.23.3; extra == "dev"
Requires-Dist: packaging; extra == "dev"
Dynamic: license-file

# 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:

```bash
pipx install book-builder
```

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

```bash
# 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:

```bash
book-builder --help
```

## Project Structure for Users

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

```text
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

```bash
# 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)

```bash
pipx install book-builder
```

### Development install

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

Requirements:

- Python 3.12+

## Development

Common Make targets:

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

Documentation lives under [docs/source](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](LICENSE).
