feat: expose FixtureFunctionDefinition for typing

[teddygood]

Closes #14853

Summary

pytest.fixture returns a FixtureFunctionDefinition, but users previously had to import this type from the private _pytest.fixtures module when annotating fixture factories.

This change exports the existing class as pytest.FixtureFunctionDefinition and adds it to the API reference. It does not introduce a new class or change fixture behavior at runtime. The supported public surface is limited to its use in type annotations. Direct instantiation, subclassing, and its attributes remain outside the public API.

A typing check covers fixture factories returning the public type. The obsolete Sphinx cross-reference exception is also removed now that the type has a public documentation target.

[RonnyPfannschmidt]

@pytest-dev/core if we expose this - do we want to make the return type a generic?

[teddygood]

This seems directly related to the TODO introduced in #12473. I found #13036, which explored preserving both the ParamSpec and return type, and it was closed due to lack of time rather than because the design was rejected.
Since the generic arity and semantics would become part of the public API, I agree that this is worth settling before exposing the type. Do we want only a declared return-type parameter, or the ParamSpec plus return-type shape from #13036? For yield fixtures, should the type parameter represent the declared Generator[...] return type or the yielded fixture value?

I’ll wait for input from @pytest-dev/core before making further changes.

[nicoddemus]

I think it makes sense to make the return type generic if possible.

[The-Compiler]

It should probably be marked @final?

[teddygood]

Thanks. I had considered whether @final was necessary, but you’re right. I’ll add it.