feat: Add Renderers for Yields

[Lawrence-Godfrey]

Should solve #338

quartodoc version: 0.11.1

Problem

Currently if I have a Yields: section in a function, e.g.,

@asynccontextmanager
async def get_session_factory(
    session_factory_instance: async_sessionmaker[AsyncSession],
) -> AsyncGenerator[AsyncSession, None]:
    """
    Yields an AsyncSession

    Args:
        session_factory_instance: An async sessionmaker instance to 'yield' sessions from and close them asynchronously.

    Yields:
        An AsyncSession instance.
    """
    async with session_factory_instance() as session:
        try:
            yield session
        finally:
            await session.close()

I get the following error:

  File "/home/.../Documents/.../.venv/lib/python3.10/site-packages/quartodoc/renderers/md_renderer.py", line 309, in render
    raise NotImplementedError(f"Unsupported type: {type(el)}")
NotImplementedError: Unsupported type: <class '_griffe.docstrings.models.DocstringSectionYields'>

Solution

Adding renderers in md_renderer.py for DocstringSectionYields and DocstringSectionYields (basically exactly the same renders for Returns) everything renders nicely.

Seems to work with parser: numpy too.
Also seems to handle interlinks correctly as far as I can tell.

[codecov-commenter]

⚠️ Please install the to ensure uploads and comments are reliably processed by Codecov.

Codecov Report

Attention: Patch coverage is 60.00000% with 4 lines in your changes missing coverage. Please review.

Project coverage is 88.75%. Comparing base (e28324d) to head (d53796e).

Files with missing lines	Patch %	Lines
quartodoc/renderers/md_renderer.py	60.00%	4 Missing ⚠️

❗ Your organization needs to install the Codecov GitHub app to enable full functionality.

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #402      +/-   ##
==========================================
- Coverage   88.86%   88.75%   -0.11%     
==========================================
  Files          40       40              
  Lines        3027     3033       +6     
==========================================
+ Hits         2690     2692       +2     
- Misses        337      341       +4     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[machow]

Thanks so much for adding this! I'm dumping the numpydoc yields spec below, just so I can quickly reference:

[machow]

This seems pretty straightforward, and should be quick to merge! Would you mind adding a simple test? I think it'd be okay to just duplicate this returns test for now.

(I'm always happy to swing in and add the test if useful :)

edit: I think the CI for doc build will always fail, since it's an external PR. I can fix separate from this PR 😓.

[Lawrence-Godfrey]

This seems pretty straightforward, and should be quick to merge! Would you mind adding a simple test? I think it'd be okay to just duplicate this returns test for now.

(I'm always happy to swing in and add the test if useful :)

edit: I think the CI for doc build will always fail, since it's an external PR. I can fix separate from this PR 😓.

Have added testcases for Numpy and Google style docstrings with Yields in them.

[SalmanMohammadi]

Hi @machow @Lawrence-Godfrey - is this still planned? We're also running into this issue and the fix would be great to have.

[Lawrence-Godfrey]

Hey @machow, any updates on this? Would be great to get it in. Let me know if there's something I need to do here.