[ingehap]

Summary

Every docstring source in petrolib now resolves to a complete journal citation, in two layers:

1. Per-function/class Sources: tags (195 new). The newer modules (acoustic_geomech, em_dielectric, nuclear, integrity_drilling, the inversion_numerics package, wellbore_geometry, depth_correction, depth_matching, borehole_image, units, constants, and parts of data_qc_io) had no source tags at all. Their provenance was recovered from the delegation graph: a corpus scan of all srcYYYY_MM directories mapped every petrolib.<module>.<function> call site, and each previously untagged public function/class gained a Sources: srcYYYY_MM/<module> line listing the article files that delegate to it (capped at 8 + "and N more articles" — inversion_numerics.fitting.fit_line tops out at 41 callers). 95 definitions with no direct article caller (internal helpers reached via sibling wrappers, canon-completion functions) are left untagged, per "if possible".

2. Module-level References sections (36 modules). Every module whose docstrings carry source tags gains a References section in the module docstring giving the complete citation for each tag: title, authors, year, Petrophysics volume/issue/pages, and DOI. Citations are extracted from the article files' own headers; formal Reference:/Based on: blocks are used verbatim when present; volume/issue/date come from the plan's directory table when a header lacks them; pre-2017 issues carry the honest "DOI: none assigned (this issue predates SPWLA DOI assignment)" note. Bare-directory mentions in prose (e.g. "src2016_10 uses signed cos") get issue-level citations.

Example entry:

src2023_08/article5 -- Merletti, G., Rabinovich, M., Al Hajri, S., Dawson, W., Farmer, R., Ambia,
  J., Torres-Verdín, C. (2023). "New Iterative Resistivity Modeling Workflow Reduces Uncertainty in
  the Assessment of Water Saturation in Deeply Invaded Reservoirs", Petrophysics, Vol. 64, No. 4,
  pp. 555-567. DOI: 10.30632/PJV64N4-2023a5.

This keeps function docstrings readable (shorthand tags as before) while making every tag resolvable to a full reference within the same file — the same pattern as a keyed bibliography.

Verification

Docstring-only change — no code paths touched:

• ruff check + ruff format --check clean (all wrapped ≤ 100 columns);
• python3 -m mypy petrolib clean (45 source files);
• python3 -m pytest tests/petrolib: 252 passed;
• import smoke-tested; one-liner docstrings correctly converted to multi-line on insertion.

🤖 Generated with Claude Code

https://claude.ai/code/session_01B2BX1XL8422gebCU1oVoQC

---

Generated by Claude Code