Add describe_method() for structured parameter introspection

[caiocrocha]

Summary

The current describe_api implementation lists API method names and summaries, however there was no easy way to programmatically discover a method's parameters (names, types, defaults, descriptions).

The proposed describe_method method extracts this information from a method's docstring and returns a DataFrame containing one row per parameter, including its name, type, description, and default value. Example usage (Python console):

poetry run python -c "import malariagen_data; \ 
ag3 = malariagen_data.Ag3(); \
df = ag3.describe_method('snp_allele_frequencies'); \
print(df.head(3));"

Output:

parameter	type	default	description
transcript	Optional[str]	None	Gene transcript identifier.
region	Union[str, malariagen_data.util.Region, Mapping[...]]	None	Region of the reference genome. Can be a conti...
cohorts	Union[str, Mapping[str, str], NoneType]	None	Either a string giving the name of a predefine...

Related Issues

Directly addresses: #1262

Relates to: #1238, #1141, #1123.

Why? All issues above mention difficulties in discovering the API and function arguments, including lack of interactive documentation, hard learning curve, and unclear parameter schema. The current PR contributes to more discoverable methods. In addition to the describe_api method, describe_methods can significantly simplify discovering the parameters of the API methods.

Changes Made

Added a new describe_method(method_name) method to AnophelesDescribe that returns a DataFrame with columns: parameter, type, default, description. Includes _parse_param_docs() helper and 6 new tests.

Testing

Implemented tests:

Returns DataFrame: Verifies output structure with required columns (parameter, type, default, description);

Error Handling: Validates ValueError for non-existent methods;

Smoke Test: Uses "sample_sets" method to confirms it works on real methods;

Correct @doc() Parsing: Verifies parameter parsing from NumPy docstrings;

Empty Parameter: Tests passing empty parameters;

Keyword Arguments: Tests *args and **kwargs extraction.

Checklist

I have followed the steps covered in CONTRIBUTING.md:

[X] Tests pass locally

[X] Pre-commit hooks pass (or run pre-commit run --all-files)

[X] Code is well-documented

[X] Commit messages are clear and descriptive