Make describe functions available to reporting

[joshuaprior]

What's changing

This change exposes a new API on collected test items called Item.get_describe_function_heirarchy(). This function allows reporter plugins to gain access to the describe functions that were used to define the test suite structure.

API changes

Item.get_describe_function_heirarchy()

• Returns a list of all the ancestor describe functions that wrap around the test item.
  • The list is ordered starting with the describe that is closest to the test item.
• Delegates to the property DescribeBlock.describe_function_heirarchy to get the list.

DescribeBlock.describe_function_heirarchy

• Computes the hierarchy from this describe up to the top most describe. Includes this describe in the list.
• Memoizes the result so it doesn't need to be computed for every test item.
• Does not compute the list until it is requested, so there is no wasted effort if the new API is not used.

Planed integration

I have implemented a change in pytest-spec to use this new API to provide docstring support for formatting describe statements.

[joshuaprior]

I didn't see any unit tests for the DescribeBlock class so I didn't add any tests for this change. If you would like to give some guidance (file location, test structure) on how you would want the tests to look, then I would be happy to write some to cover this change.

[Cito]

Thank you for this PR and for the pytest-spec integration you prepared on top of it, and please accept my apologies for the long silence here, especially after you explicitly asked for guidance on testing and never got an answer.

In the meantime, plugin.py was substantially reworked (type hints, fixtures as describe arguments), so this PR no longer applied cleanly. Since I want to ship this capability in the upcoming release now, I implemented a slimmed-down variant in #55 instead of asking you for yet another round here, sorry for sidestepping you on that. It exposes a documented public helper get_describe_functions(item) based on item.listchain(), which should serve your pytest-spec integration just as well, and the PR credits you for the idea.

I'd be happy to hear your feedback on #55, in particular whether the API works for your pytest-spec changes. Thanks again for pushing this forward!