feat: place description line just below title (and above signature block)

[rich-iannone]

This PR includes a new option (desc_first) that reorders the docs output so as to place the first paragraph of a docstring (taken as the the description) between the title and object signature. I think by doing so, it makes it easier for readers to quickly understand what a function/class does before going into the details.

So with desc_first: true, this is the revised order:

1. title (function/class/method/etc. name)
2. description (first paragraph, styled with italic and tighter spacing)
3. signature (in a code block)
4. remaining content (additional paragraphs)
5. parameters, etc.

The default behavior (desc_first=False) is unchanged, so this is backwards compatible.

I used this branch to render the Great Tables docs to ensure it looks visually correct: https://pr-790--gt-python.netlify.app/reference/gt.tab_header#great_tables.GT.tab_header

Here's how it looks:

Before the change:

The following inline styles are used for the description line:

font-size: 1rem;
font-style: italic;
margin-top: -10px;
line-height: 1;

I added a few tests in test_renderers.py.

[machow]

Thanks so much for taking the time to submit this. I personally think that using the "short summary" as a description under the title is a nice design. I think one of the challenges here is that the concept of a short summary might be numpydoc specific.

For example, I don't think the short summary is explicitly represented in griffe.

from quartodoc import preview
from griffe import Docstring, Parser
from quartodoc.parsers import get_parser_defaults

doc = """I am the short summary.

I am the extended summary. I am encouraged to be longer.

Examples
--------

abc
"""

docstring = Docstring(value=doc, parser=Parser.numpy, parser_options=get_parser_defaults("numpy"))

preview(docstring)

Notice that the short summary and extended summary are represented as a single DocstringSectionText node.

titles in R vs Python docs

I know the design of putting the description under the title is very R pkgdown. However, I wonder if the concept of title is modeled a bit more explicitly in roxygen2?

That said, we do already pull out the first sentence of docs (e.g. basically the short summary) to use in the index:

[machow]

@gadenbuie wdyt of putting the description just below the title?! I feel like you've got a good eye for this stuff!

[codecov-commenter]

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

Codecov Report

❌ Patch coverage is 88.39286% with 13 lines in your changes missing coverage. Please review.
✅ Project coverage is 88.94%. Comparing base (e28324d) to head (e2121b7).

Files with missing lines	Patch %	Lines
quartodoc/renderers/md_renderer.py	80.59%	13 Missing ⚠️
❗ Your organization needs to install the Codecov GitHub app to enable full functionality.

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #405      +/-   ##
==========================================
+ Coverage   88.86%   88.94%   +0.07%     
==========================================
  Files          40       40              
  Lines        3027     3121      +94     
==========================================
+ Hits         2690     2776      +86     
- Misses        337      345       +8     

☔ 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.

[pawamoy]

@machow I think the short summary is standard, and described/recommended in a docstrings-related PEP (can't remember all the PEP numbers hehe).

I'm totally open to add a summary property on Docstring objects. It would be very naive and return the first line.

[machow]

Sorry for being late to this, and thanks @pawamoy! A .summary property seems great! I'm down to open a PR on griffe if useful :)