[ingehap]

Summary

Adds doc/Petrophysics_Handbook.pdf (A4, 518 pages), a professional user manual for the petrolib library, with the requested fixed layout:

• Title page carrying exactly three lines: Petrophysics Handbook, Code for Petrophysics Jan/Feb 2014 - Jun/Jul 2026, and https://github.com/ingehap/Petrophysics_Code — no other text (no header/footer on this page).
• A blank page.
• Table of contents (12 pages): all 504 public petrolib functions in alphabetical order, each entry linked to its page.
• One page per function, in alphabetical order, each giving: the Python path to the function, a blank line, the purpose, a blank line, the input parameters (name, type, default, and the meaning of each parameter), a blank line, the output parameters, a blank line, and the sources where they exist — as full SPWLA Petrophysics journal citations (title, authors, year, volume/issue/pages, DOI) resolved from the module docstrings' References sections. 406 of the 504 functions carry citations; the remainder have no Sources: tag in their docstring.

Implementation

• tools/gen_petrolib_handbook.py reworked for this layout: functions only (module-level constants and the 6 classes are no longer included), one page per function guaranteed via shrink-to-fit framing, output moved from docs/ to doc/, and source tags now parsed from the Sources: clause only — with a prefix fallback so bare srcYYYY_MM tags still resolve to full citations (previously one tag leaked from prose and one stayed unresolved).
• tools/handbook_descriptions.json (new): per-function parameter meanings and output descriptions for every parameter of all 504 functions, written from the function bodies, docstrings, and module unit conventions. The generator reads it at build time and reports any missing description or citation on stderr, so the file stays honest as the API evolves.
• README.md / docs/petrolib.md: handbook links now point at the doc/ location.

Regenerate after petrolib changes with python tools/gen_petrolib_handbook.py (needs pip install reportlab, or pip install -e ".[docs]").

Verification

Programmatic checks on the generated PDF (pdfminer): the title page contains exactly the three specified lines; page 2 is empty; ToC entries are in alphabetical order with correct page numbers; each of the 504 functions starts its own page and every page contains the Purpose / Input parameters / Output parameters sections; zero unresolved parameter descriptions or citations at build time. The densest pages (e.g. vshale_from_gr with 6 parameters, 6 citations) were visually inspected and fit on a single page.

🤖 Generated with Claude Code

https://claude.ai/code/session_01VBtq2fm3n7iG6y7i3mvz3K

---

Generated by Claude Code