docs: improve search discoverability

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,
             )
         )

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

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)

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