Adds pytest_markdown_docs_markdown_it for custom markdownit parser

[thomasjpfan]

Issue: Fixes #31

This PR adds a pytest_markdown_docs_markdown_it pytest hook to allow developers to customize the markdown_it parser. This means they can add plugins such as admon_plugin to the parser.

An alternative is to add something like https://github.com/modal-labs/pytest-markdown-docs/blob/main/src/pytest_markdown_docs/_runners.py, but using a pytest hook feels a little more natural with how pytest does things. For example, pytest-xdist has uses a pytest_xdist_make_scheduler to configure a custom scheduler:

https://github.com/pytest-dev/pytest-xdist/blob/f83299cd646965ac0560adddcf7204adde9f486e/src/xdist/newhooks.py#L96-L100

[freider]

Thanks for the contribution! I like the pytest hook pattern for this, since the markdown flavor is probably going to be the same across a codebase anyways.

[freider]

I might be missing something here, but why is this a list? (seems like we are throwing away anything except the first element anyway)

[thomasjpfan]

Pytest returns a list because the hook can be defined multiple times. For example:

tests/
    conftest.py <- hook can be defined here
    io/
        conftest.py <- same hook can be defined here
        my_test.py

The default is to have a list that contains all the hooks and the nested conftest.py gets called first so they are first in the hooks list.

---

I simplified the code by using @pytest.hookspec(firstresult=True), which returns the first one by default: 0be6a10

Also, 5fe7f6f, which defines a default MarkdownIt parser using the hook.

[freider]

Ah I see, yeah this makes sense! Thanks for the explanation and I like the firstresult and default implementation

[freider]

Regarding the list comment above - maybe it's better to validate the hook return value here (making sure it's at most one specification, since that's what we support) and then just pass in the single MarkdownIt we want to use?

[thomasjpfan]

With 0be6a10 and 5fe7f6f, this should be a single MarkdownIt object.

The remaining user error is returning a non-MarkdownIt object:

def pytest_markdown_docs_markdown_it():
    return "abc"

Do you think it's worth checking for this edge case?

[freider]

With the other changes I don't think we need to check for anything here 👍

[freider]

lgtm, thanks!