search

machow / quartodoc

Generate API documentation with quarto
https://machow.github.io/quartodoc
MIT License
176 stars 20 forks source link

Ensure summary only uses the short description #329

Closed machow closed 8 months ago

machow commented 8 months ago

Looking at the py-shiny docs, it appears that more than just the single line description is used in the summary:

image
machow commented 8 months ago

I think it's possible this is a bug I created in griffe, or something we should be more careful of in quartodoc. Basically, there is a single DocstringSectionText for the inital 1-line summary and following description..

from quartodoc import Auto, blueprint, MdRenderer, preview
bp = blueprint(Auto(name = "shiny.reactive.event"))

# initial DocstringSectionText has both the 1 line summary and additional paragraphs
print(bp.obj.docstring.parsed[0].value)

Let's make summary always stop at the first linebreak, so no matter what the input is, the summary will be succinct.

machow commented 8 months ago

Whoops -- @schloerke pointed out that this is happening in the custom shiny renderer. (quartodoc summarize does split on linebreaks).