diff --git a/docs/hooks.py b/docs/hooks.py index d569631..2f82561 100644 --- a/docs/hooks.py +++ b/docs/hooks.py @@ -1,6 +1,5 @@ from __future__ import annotations -import re from pathlib import Path from mkdocs.structure.files import File, Files, InclusionLevel @@ -12,36 +11,22 @@ from mkdocs.structure.pages import Page -def _normalize_root_links(path: Path) -> str: - docs_re = re.compile(r'https:\/\/agrodt\.github\.io\/ptfkit\/(.+)\/') - content = ( - path.read_text() - .replace('(./', '(https://github.com/AgroDT/ptfkit/tree/main/') - .replace( - 'https://agrodt.github.io/ptfkit/contributing/development/', - 'contributing/development.md', - ) - ) - return docs_re.sub(r'\1/index.md', content) - - GENERATED_PAGES = ( - ('README.md', 'index.md', _normalize_root_links), - ('CONTRIBUTING.md', 'contributing/index.md', Path.read_bytes), - ('targets/ptfkit-native/README.md', 'targets/native.md', Path.read_bytes), - ('targets/ptfkit-py/README.md', 'targets/python.md', Path.read_bytes), - ('targets/ptfkit-rs/README.md', 'targets/rust.md', Path.read_bytes), + ('CONTRIBUTING.md', 'contributing/index.md'), + ('targets/ptfkit-native/README.md', 'targets/native.md'), + ('targets/ptfkit-py/README.md', 'targets/python.md'), + ('targets/ptfkit-rs/README.md', 'targets/rust.md'), ) def on_files(files: Files, /, *, config: MkDocsConfig) -> Files | None: root = Path(__file__).joinpath('../..').resolve() - for source, destination, get_content in GENERATED_PAGES: + for source, destination in GENERATED_PAGES: files.append( File.generated( config, destination, - content=get_content(root / source), + content=(root / source).read_bytes(), inclusion=InclusionLevel.INCLUDED, ) ) diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index a8b2955..a365e86 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -1,4 +1,5 @@ site_name: ptfkit +site_description: Specification-driven collection of published pedotransfer functions for estimating soil hydraulic properties in Python, Rust, C, and C++. site_url: https://agrodt.github.io/ptfkit/ repo_url: https://github.com/AgroDT/ptfkit repo_name: AgroDT/ptfkit diff --git a/docs/src/index.md b/docs/src/index.md new file mode 100644 index 0000000..46365c6 --- /dev/null +++ b/docs/src/index.md @@ -0,0 +1,75 @@ +--- +title: Pedotransfer functions for soil hydraulic properties +description: ptfkit is a specification-driven collection of published pedotransfer functions for estimating soil hydraulic properties in Python, Rust, C, and C++. +--- + +# Pedotransfer functions for soil hydraulic properties + +**ptfkit** is a specification-driven collection of published pedotransfer +functions (PTFs) for estimating soil hydraulic properties. It provides +traceable implementations through consistent interfaces for Python, Rust, C, +and C++. + +Pedotransfer functions estimate soil properties from measurements that are +generally easier, faster, or less expensive to obtain directly. Common inputs +include particle-size fractions, bulk density, and organic matter content; +predicted properties in ptfkit include soil water-retention characteristics and +hydraulic conductivity. + +## Explore the PTF collection + +The [PTF catalog](ptf-catalog/index.md) connects each implementation to its +scientific source. Source pages document the publication, calibration scope, +territory, inputs, outputs, units, equations, status, numerical examples, +limitations, and warnings retained by ptfkit. + +The [PTF sources](ptf-catalog/sources/index.md) page provides an index of the +published pedotransfer-function sources currently represented in the catalog. +Use it to locate implementations by source publication and review their +applicability before use. + +## Programming-language targets + +ptfkit exposes generated implementations for several programming languages: + +| Target | Interface | Documentation | +| --- | --- | --- | +| Python | Scalar and NumPy array inputs backed by native ufuncs | [Python target](targets/python.md) · [Python API](reference/python/index.md) | +| Rust | Scalar functions grouped by source publication | [Rust target](targets/rust.md) · [docs.rs](https://docs.rs/ptfkit/) | +| C | Header-only C11 functions | [C and C++ target](targets/native.md) · [C API](reference/c/index.md) | +| C++ | Optional C++20 modules | [C and C++ target](targets/native.md) · [C++ API](reference/cpp/index.md) | + +Packages are distributed through [PyPI](https://pypi.org/project/ptfkit/) and +[crates.io](https://crates.io/crates/ptfkit); C and C++ releases are available +from the [GitHub repository](https://github.com/AgroDT/ptfkit/releases). + +## Scientific traceability + +Every PTF starts from its original scientific publication. Equations, variable +definitions, units, calibration scope, numerical examples, notes, and warnings +are transcribed into reviewed YAML specifications. Those specifications are the +target-independent source of truth from which ptfkit generates language +implementations, tests, the PTF catalog, and API reference pages. + +This design keeps the scientific description and executable implementations +aligned across programming-language targets. It also makes the source and +applicability limits of each pedotransfer function explicit rather than treating +PTFs as interchangeable empirical formulas. + +## Scope and limitations + +Pedotransfer functions are empirical models fitted to particular datasets, +territories, measurement methods, and variable ranges. Their accuracy and +applicability outside those calibration conditions are not guaranteed. + +Before using a function, review its catalog page and original publication for +the calibration dataset, input definitions, units, domains, notes, warnings, +and implementation status. + +## Project resources + +- [PTF catalog](ptf-catalog/index.md) +- [PTF sources](ptf-catalog/sources/index.md) +- [GitHub repository](https://github.com/AgroDT/ptfkit) +- [Development guide](contributing/development.md) +- [How to cite ptfkit](https://github.com/AgroDT/ptfkit/blob/main/CITATION.cff) diff --git a/targets/ptfkit-py/README.md b/targets/ptfkit-py/README.md index c267f65..befa9a1 100644 --- a/targets/ptfkit-py/README.md +++ b/targets/ptfkit-py/README.md @@ -32,7 +32,7 @@ optional `out` array can be supplied for in-place calculation. ## Documentation - [PTF source catalogue](https://agrodt.github.io/ptfkit/ptf-catalog/) -- [Python API](https://agrodt.github.io/ptfkit/reference/python.) +- [Python API](https://agrodt.github.io/ptfkit/reference/python/) - [Repository](https://github.com/AgroDT/ptfkit) The applicability of each PTF depends on the dataset, territory, measurement